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Preface 


The AT&T C-t-t- Language System Library Mamud describes the C-f+ class libraries provided with Release 
2.0 of the AT&T C++ Language System: 

■ the complex aridunetic library 

■ the task library 

■ the iostream library 

The manual is part of a set of four documents that are supfdied with your C++ Language System. The 
other documents ate: 

■ the Release Notes, ududt describe the contents of tttis release, how to install it; and dtanges to the 
language 

■ the Product Reference Manual, wdtich provides a complete definition of die C++ language sup¬ 
ported by Release 2i) of die Lai^uage System. 

■ the Selected Readings, ^lich contains papers desodsng a^iects of die C++ langiu^ 

The chapters in this manual cover die following C++ class libiaiies: 

■ Chapter 1 describes the con^lex arithmetic library, wdiidi provides a dass complex that allows 
you to declare and manipulate complex numbers in C++ programs 

■ Chapter 2 describes the task library, whidi allows you to create and control concurrent processes 
in C++ programs. The last section of Chapter 2 provides porting information for the ta^ 
library, which is machine dependent 

■ Chapter 3 describes the stream library, which allows you to do formatted input and output from 
C++ programs 

■ Appendix A contains manual pages for all three class libraiies 

To make the best use of the Library Manual, you must be familiar with die C programming language 
and the C programming environment under the UNIX® operating system. Refer to Appendix B of the 
Release Notes for further sources of information about these topics. 
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Complex Arithmetic In C++ 


! This chapter is taken directly from a paper by Leonie V. Rose and Biame Stroustruo 
NOTE i 


Abstract 


1 his memo desaibes a data type complex providing the basic facilities for using con^lex arithmetic in 
C++. The usual arithmetic operators can be used on complex numbers and a Ubtaiy of standard com¬ 
plex mathematical functions is provided. For example: 

#include <ca(nple 3 c.h> 

mainO { 

ccnplex toe; 

conplex yy » conplex(l,2.718) ; 

JQC - log(yy/3); 
cout « l+joc; 

1 

initializes yy as i complex number of the form (zeal+imag*i), evaluates the expressions and prints the 
result: (0.7061074.10715). 

The data type complex is implemented as a dass using the data abstraction facilities in C++. The 
arithmetic operators +,-,», and/, tfte assignment operators =, +=, •=, and/6:, aitd the comparison 

operators == and != are provided for complex numbers. So are the trigonometric and mathematical 
functions: sinO, cosO, coshO, sinhO, sqrt(), log(), expO, conjO, aig(), absO, nonnO, and powO. 
Expressions sudt as (xx+l)»log(yy*log(34)) that involve a rruxture of real and cortq>lex nutrtbers are 
handled correctly. The simplest complex operations, for example + and +=, are implemented without 
function call overhead. 


Introduction 

The C++ language does not have a built-in data type for complex numbers, but it does provide 
lan^age facilities for defirung rtew data types. The type complex was designed as a useful demons- 
tration of the jX)wer of these facilities. 

There are three plausible ways to support complex numbers in a language. Rist, the type complex 
could be directly supported by the compiler in the same way as the types int and float are. Alterna¬ 
tively, a preprocessor could be written to translate all use of corrq^lex numbers into expressions involv¬ 
ing only built-in data types. A third approach was used to implen«nt type complex; it was specified 
as a user -defined type This demonstrates that one can achieve the degance and most of the efficiency 
of a built in data type without modifying the compiler. It is even much easier to implement than the 
pre-processor approad\, which is likely to provide an inferior user interfoce. 
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This facility for complex arithmetic provides the arithmetic operators +,/, and the assignment 
operators =, +=, •=, and/fe, and the comparison operators = and != for complex numters. Input 

and output can be done using the operators » (get from) and « (put to). The initialization functions 
and » accept a Cartesian representation of a complex. The functions realO and imagO return the real 
and imaginary part of a complex, respectively, and « prints a complex as (ieal,imaginary) The 
internal representation of a complex, is, however, inaccessible and in principle unknown to a user 
Polar coordinates can also be used. The function polari) creates a complex given its polar representa¬ 
tion, and absO and aig() return the polar magnitude and angle, respectively, of a complex. The func¬ 
tion normO returns the square of the magnitude of a complex. The following complex functions are 
also provided: sqit(), expO, log(), sinO, cosO, slnhO, coshO, pow(), and con|(). The declaration of 
complex and the dedarations of die complex functions can be found under 'Type complex." A com¬ 
plete program using onnplex numbers can be found tmder "An FFT Function." 


Complex Variables and Data Initialization 

A program using complex arithmetic will contain declarations of complex variables. For example: 
conplex zz - CGnplez(3,-5); 

will declare zz to be complex and initialize it with a pair of values. The first value of the pair is taken 
as the real part of the Cartesian representation of a complex number and the second as the imaginary 
part. The function complexO constructs a complex value given suitable arguments.’ It is responsible 
for initializing complex variables, and will convert the arguments to die prope- type (double). Such 
initializations may be written more conqiacdy. For example: 

ccxrplex zz(3,-5); 
coopiex c_nainB(-3.9,7) ; 

CQoplex rpr(S(»TJ2,root3); 


A complex variable can be initialized to a real value by using the constructor with only one argument 
For example: ® 

conplex ra - oanplex(l); 

will set up ra as a complex variable initialized to (1,0). Alternatively the initialization to a real value 
can also be written without explicit use of the constructor 

ccnplex rb - 123; 

The integer value will be converted to the equivalent complex value exactly as if die constructor com- 
plex(123) had been used expUcidy. However, no conversion of a complex into a double is defined, so 

double dd - oaaplez(l,0); 

is illegal and will cause a compile time error. 

If there is no initialization in the declaration of a complex variable, then the variable is initialized to 
(0,0). For example: 
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complex ocig; 

is equivalent to the declaration: 

conplex orig - complex(0,0}; 

Naturally a complex variable can also be initialized by a complex expression. Fbr example: 

conplex cx (-0.5000000ef02,0.8660254e+02); 
cortplex cy - cx<flog(cx); 

It is also ]x>ssible to declare arrays of complex numbers. For example 
ccxnplex carray[30]; 

sets up an array of 30 complex numbers, all initialized to (0,0). Using the above dedarations: 

coroplex carrt] - { cx, cy, cacc^(2], canplex(l.l,2.2) 1; 

sets up a complex array cairf ] of four complex dements and initializes it the members of the list 
However, a struct style initialization caimot be used. For example: 

ccanplex cwrong[] - {1.5, 3.3, 4.2, 4); 

is illegal, because it makes unwarranted assumptions about the representation of complex numbers. 


Input and Output 


Simple input and output can be done using ttte operators »(get from) and «(put to). They are 
declared like this using the facility for overioading hmction operators: 

ostreams opecatOE«(ostzeain&, ocnplex); 
istceamfi opecatoc»(istzeaiii&, ocmplex&); 

When zz is a complex variable cin»zz reads a pair of numbers from the standard input stream cin 
into zz. The first ntimber of the pair is interpreted as the real part of the Cartesian representation of a 
complex number and tite second as tfte imaginary part. The expression cout«zz writes zz to the stan¬ 
dard output stream cout. For example: 

void copydstceanifi ficon, ostceams to) 

{ 

conplex zz; 

while (fcaai»zz) to«zz; 

} 

reads a stream of complex numbers like (3.4000004<000000) and writes them like (3.4,5). The 
parentheses and comma are mandatory delimiters for input, while white sp>ace is optional. A single 
real number, for example lOe-7 or (123), will be interpreted as a complex with 0 as the imaginary part 
by operator ». 
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A user who does not like the standard implementation of « and » can provide alternate versions. 


Cartesian and Polar Coordinates 

The functions realO and imagO return the real and imaginary parts of a complex number, respectively. 
This can, for example, be used to create differently formatted output of a complex: 

conplex cc « ccxnplex(3.4,5); 

cout « ceal(cc) « "+" « inagfcc) « "*l"; 

will print 3.4+5*i. 

The function polaiO creates a complex given a pair of polar coordinates (magnitude, angle). The func¬ 
tions aigO and absO both take a complex argument and return the angle aitd magnitude (modulus), 
respectively. For example: 

ccxiplex cc - polar(S^_2,PI/4); // also known as ocaplexd,!) 

double nagn « abs (cc); // magn - sqct (2) 

double angl - acg(cc}; // angl - PI/4 

cout « « nagn « ", a-* « angl « •)•; 


If input and output functions for the polar representation of complex numbers are needed they can 
easily be written by the user. 


Arithmetic Operators 


The basic arithmetic operators +, - (uiuuy and binary),/, and •, the assignment operators =, +=, -=, 
•=, and/fe, as well as ttve equality operators »= aitd !=, can be used for complex numbers. The opera¬ 
tors have their conventional precedences. For example: asb*ONi for complex variables a, b, c, and d 
is equivalent to as(b*c)-fd. There are no operators for exponentiation aiul conjugation; mstead the 
functions powO and conjO are provided. The operators 4^, -s, ^s, aiKl/s do not produce a value 
that can be used in an expression; thus the following examples will cause compUe time errors: 

ccnplex a, b; 

// ... 

if ( (34-2)—0 ) { 

// ... 

} 

b - a b; 
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Mixed Mode Arithmetic 

Mixed mode expressions are handled correctly. Real values will be converted to complex where neces¬ 
sary. For example: 

conplex XX(3.5,4.0); 

complex yy - log(yy) + log(3.2); 

This expression involves a mixture of real values: log(3^), and complex values: log(yy) and the sum. 
Another example of mixing real and complex, xxsl, is equivalent to xxscomplexd) whidt in turn is 
equivalent to xx=complex(l,0). The interpretation of the expression (xx+l)«yy*3^ is 
(((xx+complex(l))«yy)*complex(3^)). 


Mathematical Functions 


A library of complex mathematical functions is provided. A complex function typically has a counter¬ 
part of the same name in the standard mathematical library. In this case the fun^on name will be 
overloaded. That is, when called, the function to be invok^ will be chosen based on the argument 
type. For example, log(l) will invoke the real logO, and log(complex(l)) will invoke the complex 
logo. In each case the integer 1 is converted to the real value IjO. 

These functioris will produce a result for every possible argument If it is not possible to produce a 
mathematically acceptable result, the function complex_enor<) will be called and some suitable value 
returned. In particular, the functiotts try to avoid actual overflow, calling complex etrotO with an 
overflow message instead. The user can supply complex_etror(). Otherwise a function hat simply 
sets the integer ermo is used. See "Errors and Error Handling" for details. 

complex cx>n j (ccxiplex) ; 

Conjizz) returns the complex conjugate of zz. 

double nocmfcoRiplex) ; 

Norm(zz) returns the square of the magnitude of zz. It is faster han abs(zz), but more likely to cause 
an overflow error. It is intertded for comparisons of magnitudes. 

doiible pow(double, double); 
conplex pow(double, conplex) ; 
cxsnplex pow (cxoplex, int) ; 
conplex pow(caaplex, double) ; 
conplex pow (ccxiplex, conplex) ; 


Pow(aa,bb) raises aa to the power of bb. For example, to calculate (l-i)**4: 

cout « pow( coitplexd,-!), 4) ; 

The output is (-4,0). 
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double log(double); 
ccxiplex log (complex) ; 

Log(zz) computes the natural logarithm of 22 . Log(O), causes an error, and a huge value is returned. 

double exp(double) ; 
coirplex exp (complex); 


Exp( 2 z) computes e** 22 , e being 2.718281828... 

double sqrt(double); 
conplex sqrt (ccnplex) ; 


Sqrt( 22 ) calculates the square root of 22 . 
The trigonometric functions available are; 

double sin (double); 
complex sin (complex); 


double cos(double); 
complex cos(conplex) ; 


Hyperbolic functions are also available; 

double sinh(double); 
conplex sinh (conplex) ; 


double cosh(double); 
conplex cosh(conplex); 


Other trigonometric and hyperbolic functions, for example tanO and tanhO, can be written by the user 
using overloaded function names. 


Efficiency 


C++'s facility for overloading fuiurtion names allows complex to handle overloaded function calls in an 
efficient maimer. If a function name is declared to be overloaded, and that name is invoked in a func¬ 
tion call, then the declaration list for that function is scanned in order, and the first occurrence of the 
appropriate function with matching arguments will be invoked. For example, consider the exponential 
function: 
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double exp(double); 
conplex exp(cairplex) ; 

When called with a double argument the first, and in this case most efficient, expO will be invoked. If 
a complex result is needed, the double result is then implidtly converted using the appropriate con¬ 
structor. For example; 

ccxnplex foo - exp(3.5); 

is evaluated as 

complex foo - complex( exp(3.5) ); 


and not 


conplex £cx> « exp( cxxiplex(3.S) ); 


Constructors can also be used explicitly. For ex 2 unple: 

complex add (conplex air conplex a2) // silly tiay of doing al-i'a2 

{ 

return conplex ( real (al)-freal (a2), imag(al)'t-imag(a2) ) ; 

} 


Iidine functions are used to avoid function call overhead for the simplest operatioits, for example, 
conjO, +, +=, and the constructors (See 'Type complex"). 


Type complex 


This is the definition of type complex. It can be included as <complexii>. A friend declaration 
specifies that a function may access the internal representation of a complex. The standard header file 
<:stream.h> is included to allow declaration of the stream I/O operators « and » for complex 
numbers. 

♦include <streain.h> 

♦include <errno.h> 

♦include <nBth.h> 


class complex { 

double re, im; 

public: 

complex {) { re-ijn-0; ) 

complex (double r ■ 0, double i) { re*r; ) 

friend double abs (conplex); 
friend double norm (conplex) ; 
friend double arg (conplex); 
friend conplex conj (conplex) ; 
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}; 


friend 

friend 

friend 

friend 

friend 

friend 

friend 

friend 

friend 

friend 

friend 

friend 

friend 

friend 


cocnplex cos (conplex) ; 

coiqplex oosh (oonplex); 

con^lex exp (complex); 

double imag (ocoplex) ; 

complex log (complex); 

complex pow (double, complex) ; 

complex pow (complex, int); 

complex pow(complex, double); 

complex pow (complex, complex) ; 

complex polar (double, double - 0) ; 

double real (complex); 

complex sin (complex) ; 

complex sinh (complex) ; 

complex sqrt (complex) ; 


friend complex operator+ (complex, complex) ; 
friend complex operator- (complex) ; 
friend complex operator- (complex, complex) ; 
friend complex operator* (complex, complex) ; 
friend complex operator/ (complex, complex) ; 
friend int operator— (complex, complex) ; 
friend int aerator!-(complex, complex); 


void operator4—(complex) 
void operator—(complex) 
void operator*-(complex) 
void operator/-(complex) 


ostrearoi operator«(ostreainfi, complex); 
istreamfi operator»(istreains, complex£) ; 

inline complex operators (complex al, complex a2) 

{ 

return complex (al. re+a2 .re, al. imH-a2. im) ; 

) 

inline complex operator-(complex al, complex a2) 

{ 

return complex(al.re-a2.re, al.ijn-a2.im) ; 

) 

inline cc»Tplex operator-(complex a) 

{ 

return complex (-a.re, a.imO; 

} 

inline complex conj(complex a) 

{ 

return ccxrplex (a. re, -a. im) ; 

} 
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inline inn operator*—(catplex a, cotiplex b) 

{ 

return (a.re—b.re &£ a.i m ■ ‘ b .im); 


inline inx. operator!-(ccanplex a, complex b) 

{ 

return (a.re!*b.re I I a.iml-b.im); 

) 

inline void conplex.operator-*—(complex a) 

( 

re 4— a.re; 
im 4— a.im; 

) 

inline void complex.operator—(oonplex a) 

{ 

re — a.re; 
im — a.im; 

) 


An FFT Function 

Transcribed from Fortran as presented in '"FFT as Nested Multiplication, with a Twist" by Carl de 
Boor in SIAM Sd. Stat. Comput., Vol 1 No 1, March 1980. 

tinclude <coniplex.h> 

void fftstp(complex*, int, int, int, conplex*); 
const NEJCmx = 12; 

int prime[NEX3MX] - ( 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37 ); 

conplex* fft(conplex *zl, conplex *z2, int n, int inzee) 

/• 

Construct the discrete Fourier transform of zl (or z2) in the 
Cooley-Tukey %fay, but with a twist. 

zl [before], z2 [before]. 

inzee»l meaiis ii^ut in zl; inz ee 2 means ii^ut in z2 

*/ 

{ 

int before » n; 
int after » 1; 
int next « 0; 
int now; 

do { 

int np - prime[next]; 
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if { (before/np)*np < before ) { 

if (++next < KEXmX) continue; 
now ■ before; 
before - 1; 

} 

else ( 

now ■ np; 
before /- np; 

) 

if (inzee ~ 1) 

fftstptzl, after, now, before, z2); 

else 

fftstp{z2, after, now, before, zl); 
inzee - 3 - inzee; 
after now; 

} while (1 < before) 

return (inzee—1) ? zl : z2; 


void fftstp (conplex* zin, int after, int now, int before, conplex* zout) 

zin (after, before, now) 
zout(after,now,before) 

there is anple scope for optimization 

*/ 

{ 

double angle - PI2/(now*after); 

corrplex omega » coirplex (cos (angle), -sin (angle)) ; 

complex arg - 1; 

for (int 3 - 0 ; j<now; j++) { 

for (int ia«K); ia<after; ia++) { 

for (int ib-0; ib<befoce; ib++) { 

// value - zin(ia,ih,now) 

complex value - 2 in[ia + ib*after + (now-1)*before*after]; 

for (int in-now-2; 0<-in; in—) { 

// value - value*arg + zin(ia, ib,in) 
value *- arg; 

value 4- zintia + ib*after + in*before*after]; 

// zout(ia, j,ib) - value 

zout(ia + j*after + ib*now*after) - value; 

} 

arg *- omega; 

) 

) 

} 
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The main program below calls fftO with a sine curve as argument. The complete unedited output is 
presented on the next page. All but two of the numbers ought to have been zero. The very small 
numbers shows the roundoff errors. Since C++ floating-point arithmetic is dot>e in double-precision 
these errors are smaller than the equivalent errors obtained using the published Fortran version. 

tinclude <complex.h> 

extern conplex* fft (ccaiplex*, conplex*, int, int) ; 

mainO 

/» 

test fft 0 with a sine curve 

•/ 

{ 

const n ■ 26; 

conplex* zl irew conplex [n]; 
conplex* z2 new conplex [n] ; 

cout « "input: \m"; 
for (int i-0; i<n ;i++) { 

zl(i] - sin(i*PI2/n); 
cout « zl[i] « "Vm"; 

} 

ermo » 0; 

conplex* zout - fft(zl, z2, n, 1); 

if (ermo) cerr « "Cerror " « ermo « " occurredXm"; 
cout « "output: \in"; 

for (int j=0; j<n ;j++) cout « zout[j] « "\m"; 


input: 

(0, 0) 
(C.23S316, 

0) 

(0.464723, 

0) 

(0.663123, 

0) 

(0.822984, 

0) 

(0.935016, 

0) 

(0.992709, 

0) 

(0.992709, 

0) 

(0.935016, 

0) 

(0.822984, 

0) 

(0.663123, 

0) 

(0.464723, 

0) 

(0.239316, 

0) 

(4.35984e-17, 

(-0.239316, 

0) 

(-0.464723, 

0) 

(-C.663123, 

0) 

(-0.822984, 

0) 
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(-0.935016, 0) 

(-0.992709, 0) 

(-0.992709, 0) 

(-0.935016, 0) 

(-0.822984, 0) 

(-0.663123, 0) 

(-0.464723, 0) 

(-0.239316, 0) 
output: 

(9.56401e-17, 0) 
(-3.76665e-16, -13) 
{9.39828e-17, 1.11261e-17) 
(6.42219e-16, -4.20613e-17) 
(7.37279e-17, 2.33319e-16) 
(2.85084e-16, 2.87918e-16) 
(4.03134e-l?» 5.1789e-17) 

(2.60865e-16, 6.78794e-17) 
(-5.71667e-17, -3.86348e-17) 
(2.76315e-16, 2.36902e-17) 
(-6.43755€-17, -3.80255e-17) 
(1.95031e-16, 9.77858e-17) 
(1.49087e-16, -7.57345e-17) 
(3.17224e-16, 1.64294e-17) 
(1.49087e-16. 7.57345e-17) 
(2.7218e-16, -4.03777e-17) 
(-6,43755e-17, 3.80255e-17) 
(4.93805e-16, 3.36874e-17) 
(-5.71667e-17, 3.86348e-17) 
(7.86047e-16, -4.11068e-18) 
(4.03134e-17, -5.1789e-17) 
(1.60788e-15, -1.06841e-16) 
(7.37279e-17, -2.33319e-16) 
(5.45186e-15, 2.42719e-16) 
(9.39828e-17, -1.11261e-17) 
(-1.12013e-14, 13) 


Errors and Error Handling 

These are the declarations used by the error handling; 
int ern»; 

int conplexjerror(int, double); 

The user can supply complex eiroiO. Otherwise a function that simply sets ermo is used. The excep¬ 
tions generated are; 
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CX)Sh(z2): 

C COSH RE 
C]]COSH~IM 

1 zz.re 1 too large. Value with correct angle and huge magiutude returned. 
1 zz.im 1 too large. Complex(0,0) retunved. 

exp( 22 ): 

C EXP RE POS 

c"exp re“neg 

C^^EXPJM 

2 z.im too small. Value with correct angle arKl huge magiutude returned. 
zz.re too small. Complex(0X)) returned. 

1 zz.im 1 too large. Com|^ex(0,0) returned. 

log( 22 ): 

C_LOG_0 

2Z==0. Value with a large real part and zero imagirrary part returned. 

sinh(zz): 

C SINH RE 
CJINHjM 

1 2 z.re 1 too large. Value with correct artgle and huge magnitude returned. 

1 Z 2 .im 1 too large. Complex(0,0) returned. 


Complex Arithmetic in C++ 
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Footnotes 


1. Such a function is called a constructor. A constructor for a type always has the same name as 
the type itself. 
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Introduction 


Roadmap for the C++ Task Library Documentation 


The three sections of this chapter describe the C++ Language System coroutine or task library. 

■ The first section, "A Set of C++ Cl a s s es for Co-routine S^le Progranuning," written by Bjame 
Stroustrup and revised aiKl updated by Jonathan Shopiro, describes how the task library can be 
used. Read this section to learn about the basic use of the task library. 

■ The second section, "Extending the C++ Task System for Real>TiiiK Qmtrol," by Jonathan Sho¬ 
piro, describes new features of the task library to enable tasks to receive UNIX ^em signals. 

■ The task ^tem internals for Rdease 2.0 are described in the third section, "A Porting Guide for 
the C++ Coroutine Library," by Stacey Keenan. This part tells you about the internals of the 
task library. 

■ Man pages for the task library may be found in Appendbc A of Otis manual. 


The Task Library 
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A Set of C++ Classes for Co-routine Style Programming 


NOTE ; 


This section is taken directly from a paper by Bjarne Stroustrup and Jonathan E. Shopiro. 


Abstract 


Some programs are most naturally expressed as a set of rdatively independent activities communicat¬ 
ing to achieve a common goal. Each activity, here called a toslt, has its own locus of control, a pro¬ 
gram to execute, and its own private data. Tasks can communicate by explicit sharing of data, by mes¬ 
sages, or by data pipes. ' ^ 

This paper describes C+-*- c lass es for a range of styles of multi-programming techniques in a single 
language, single address-space environment Each task is an instance of a user-defined Hacc derived 
from class task, and the program of the task is the constructor of its rla<g A task can be suspended 
and resumed without interfering with its internal state. C3ass qhead and class qtail enable a wide 
range of message passing and data buffering schemes to be implemented simply. 

The task system can be used for writing event driven simulations. Tasks execute in a simulated time 
frame presented by die variable clock, and objects of dass timer provide a convenient and efficient 
facility for using the clock. 

The implementation and use of these concepts rely heavily on the idea of derived riacw Familiaritv 
with the C++ language would be an advantage for the reader. 


Introduction 


Some programs are most naturally expressed as a set of relatively independent activities communicat¬ 
ing to achieve a common goal. Such activities, here called fasfe, must be able to execute in parallel 
with each other and conununicate through nteans convenient to the chosen style of task usage. 

Facilities for multi-thread computation can be provided in the semantics of a language, as is done in 
Concurrent Pascal and Mesa or a language without such facilities can be augmented using sp>ecial 
run-time support systems and library functions, as has been done for BCPL and C The use of C 
classes to implement tasks represents an intermediate app>roach pioneered by Simula67. 

The tools presented here^ provide die basic facilities for several styles of multi-thread programming in 
a single language, single address-^ce enviroiunent. The underlying facility is a simple and efficient 
tasking system with non-preemptive scheduling. That is, a task will only be suspended on its own 
request, so no “^tem policy" can be enforced without the coop>eration of all tasks. In contrast to 
pure co-routine systems, however, the task ^em provides a fiamework for processor sharing and 
communication between tasks. The task system is intended for applications, like event driven simula¬ 
tions, where tasks are used to express a quasi-p>arallel structure for a single program. For this class of 
applications a concept of simulated time is implemented. A unit of simulated time can represent any 
amount of real time, and it is possible to compute without consuming simulated time. A few simple 
random number generating classes and a histogram class for data gathering are also provided. The 
task system is not intended for handling real parallelism of some underlying real-time system. Conse¬ 
quently, no facilities are provided to map interrupts and other real-time events into the concepts 
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provided by the task system. 

The current version of the ta^ library has a new degree of extensibility, so that it is 
now possible to write a class that represents an irrterrupt or signal that can be waited 
for. 

Implementations of the task system have been used for about eight years on the UNIX ^tem and 
other operating systems on 3B2, 3B20, VAX, and Motored 680x0 hardware. 

In the following sections the task library will be described in some detail, aitd examples of its use will 
be given. The classes used in the task system are presented. This allows a detailed and ^)ecific dis¬ 
cussion of the concepts involved, but it unfortuiuitdy also iii^>lies that some amcepts cannot be 
explained in detail where they are first nnentiorted. 


Tasks 

The publicly accessible functions and data of dass task look like this:^ 


class task ; public sched 
{ 

public; 




task (char* naine-4, int mode^, int stacksize-O); 
-taskO ; 


task* 

t_riejtt; 


char* 

t_naine; 


int 

%#aitvec (object**) ; 


int 

waitlist(object* ...) ; 


void 

wait(object*); 


void 

delay(int); 


int 

preempt () ; 


void 

sleep(object* t -0); 


void 

resultis(int); 

1; 

void 

cancel(int); 

The base class, sched, is responsible for scheduling and for the functioruility that is common to 
and timers (described below). The public part of its declaration is; 

class 

sched : public object { 

public 

• 

sched0; 


void 

setclock(long); 


long 

rdtirneO ; 


int 

rdstate () ; 


int 

peitding () ; 


void 

cancel(int); 

}: 

int 

result 0; 

Class sched is used strictly 

as a base class; that is, only instances of derived classes are created. 


The Task Library 
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A task IS a locus of control, a virtual processor. It too can only be used as a base class A task exe- 
oi to the program supplied as the constructor of the derived dass.^ The most basic feature ^a is 
hat it<an be suspend^ and later resun^ so Aat several tasks can run in quasi-parallel. Most 
member fuitcbons of class task are coixlitional or unconditioiud requests for su^)etuion. 

A task can be in one of three states: 


RUNNING 

IDLE 

TERMINATED 


pe task is executing instructions or it wiD be scheduled to do so without 
further mtervendon from other 


pe tosk is iwt in the RUNNING state, but it can be transferred to the RUN¬ 
NING state by some suitable action. That is, it is waiting. 

The task has completed its work. It cannot be resumed, but its result can be 
retneved. 


The function schedsrdstateO returns the state. 


^ u to run in parallel with itself 

^ produced by the "secondary" task. For example, a task SwA 
counts the number of spaces in a stnng could be declared. Fiist a ciass Spaces must be declared 


class Spaces ; public 
{ 

public: 


}; 


Spaces (diar*); 


d^nHon is trirtal. It stales that Spaces is derived fnm dess 


task so 
the task . 


Spaces::Spaces(register char* s) 

{ 

register int i - 0; 

register char c; 

trhile (c - *s++) 

if (c — ' ') i++; 
resultis(i); 

} 


TOs funrtoncoTOtspe spaces in its argument string and returns the result using the class task func¬ 
tion resultisO. A task of class Spaces can now be created and u sed like this: 


Spaces ss("a line with four spaces"); 
// ... 

count - ss.resultO; 


cj^ Spaces is created, like ss here, its constructor becomes a new task that runs in 
parallel with the task that created it. A task can "return" an integer^ value using the function 

TERMINATED and the value is available for examination 
by the function schednresultO. That is, in this example ss will caU resultisO with the argument 4 
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which will be returned from sched:aesult() to the parent task. If a task calls resultO for another task 
which has not yet completed the calling task will suspended. After the other task finishes the call 
to resultO in the waiting task will return. A task waiting for another to complete is IDLE If a 
calls resultO for itself it will cause a run time enor.^ 

A task cannot return a value using the usual function return mechanism; it must use resultisO. This 
function puts the task into the TERMINATED state from which it caiuiot be resumed. 


Queues 

A queue is a type of storage that is organized so that objects are retrieved from it in the order in which 
they were inserted into it. A queue has a head from whidi data is retrieved and a tail where data is 
inserted. With a little elaboration diis basic type of data structure makes an excellent inter-task com¬ 
munication facility. 

There is no "class queue" available to a user. Instead, die two qhead and qtail provide the ser¬ 

vices needed. There is a function qtailsputO which adds an object to the foil of a queue and a function 
qheadsgetO which retrieves an object from the head of a queue. This allows explicit separation 
between the source and the recipient ot data. The public part of the dedaration of rfagg qhead looks 
like this: 

class ^lead : public object 
1 

public: 


object* 

q^dlint ^MXE, int -10000); 
-<^»ead() ; 
get 0 ; 

int 

putback Inject*); 

int 

cdoountO; 

int 

rdnodeO ; 

int 

zdnaxO; 

void 

setmode (int) ; 

void 

setnax<int); 

qtail* 

tail 0 ; 

c^iead* 

cutO; 

void 

splice (q[tail *); 

int 

pending 0; 

void 

print (int, int -0); 


); 

A queue can be created like this: 


c^iead 

To obtain a qtail for an existing queue execute tailO for its head: 


The Task Library 
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qtall* qtp - qh.tailO; 

The queue could now be used as a one way inter-task communication channel by giving its head and 
tail as arguments to two new tasks. Producer and Consumer 

Producer pp(qtp); 

Consumer cc(&q^); 


The producer task pp can now put() objects to the tail of the queue (denoted by the pointer qtp) and 
the consumer task cc can get() those objects from its head (denoted by the pointer &qh). The function 
qtailrputO takes a pointer to a class object as argument, and qheadr^etO returns such a pointer. 
Unless the user has specified ofiterwise a task executing qheadi^eK) will be suspended temporarily if 
the queue is empty. After another task executes puK) on the associated queue tail the su^>ended task 
will be resumed. Similarly a task executing qtailsputO on a full^ queue will be suspended until some 
other task removes data f^m fite queue. 

The objects transmitted through a queue must be of dass object or of some fla«; derived horn it 
Class object (described under 'The object Class") is fnovided by the task ^tem, and it is up to the 
programmer to define types of objects suitable for each a|>plication. 

In the current version of the task library qhead and qtail have the form of user exten¬ 
sions, but in the original version they were built in. Since extensbiiity was limited, the 
supplied classes had to support a wide range of programming styles. Thus they may 
seem Teature-hch." The new organization makes it easy to provide new kinds of 
queues and other fonns of task interaction. 

A Server Example 

As an example of the use of tasks and queues we will define a "server" task that receives requests for 
service in the form of messages on a queue, harulles the requests and returns replies on other queues. 
One could define a class Message as follows: 


class Message : public object 
{ 


public: 


int 

r_operation; 

int 

r_argl; 

int 

r_arg2; 

qtail* 

r_reply; 


A message, that is an object of class Message, describes an operation r_operation that is to be per¬ 
formed by the recipient of the message. Arguments for this operation can be passed as r_argl and 
r_aig2, and the result of the operation is to be returned as a message on the queue denoted by r_reply. 

A server for these nnessages can be defmed as follows: 


class Server : public taslc 

{ 

public: 

Server(qhead •); 
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); 


Server::Server(^lead* in) 

{ 

for (;;) { 

Message* req - (Message *) in->get(); 

qtail* reply - req->r_reply; 

ixit res - VALDE; 

Int val; 

switch {req->tjoperation) { 

case PLUS: 

val - req->r_argl + teq->r_arg2; 

break; 

case HINDS: 


default: 
res • ERRf^; 

) 

req->rjoperation ■ res; 
req->r_argl - val; 
reply->put(req) ; 

) 

} 


This style of server has proved useful in many contexts. In particular, it is the backbone of many 
"messagebased systems." In this particular example a server, that is an object of class Server, and the 
queue on which it depends can be declared: 

qtail* rq ■ new qtail; 

Server* ser - new Server(rq>>head()); 


Other tasks can now send a request to this particular server through zq. For example: 


The Task Library 
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(^xead rply; 

qtail* tply_to - rply.tail(); 

Message* mess •- new Message; 


mess->r_(^eration « PIUS; 
roess->r_argl ■ 1; 
iness->r_arg2 - 2; 
mess->r__teply - rply_to; 


rq->put Cmess); 

mess • (Message *) rply.get (); 
if (mess->r_operation — error (); 
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More about Queues: Mode and Size 

A queue head has a mode that controb what happens when geK) is executed on an empty queue. In 
EMODE this causes a run time error. In ZMODE it %vill cause get() to return the NULL pointer 
instead of a pointer to an object. In WMODE a task executing a get!) on an empty queue will wait on 
that queue until the queue b^mes non-empty. Unless the user specifies the mode explicitly a queue 
head will be in WMODE The function qheadsrdmodeO returns the current nnode and 
qhead:»etmodeO can be used to change it. 

As mentioned above a queue also has a maximum size. This can be diattged using qheadxsetmaxO, 
and read using qheadsidmaxO. 

The ittode and maximum size for a queue can also be qjedfied when fite queue is created. For exam¬ 
ple: 


c^ead Q1 (ZMDDE, 10) ; 

(^ead* « rtew q^read (EMODE, 64*BUFSIZE); 


The pubUc part of the declaration of class qtail is similar to that of class qhead. The two com¬ 
plement each other, and togefiier th^ provide a representation of the general idea of a queue: 


class qcail : public abject 
1 


public: 


1 ; 


// ... 

qtail (int - ftCDE, int - 10000); 
-qtail 0 ; 

int put(object*); 

int cdspace(); 

int cdnexO; 

int cdnodeO; 

qtail* cut (); 

void splice (^lead*); 

^lead* headO; 

void setaode (int in) ; 

void setinax(int a); 

int pendingO; 

void print (int, int H)); 


A queue tail's mode controls what happens on queue overflow in the sarite way as a queue head's 
mode controls what happens on queue undoflow. For exanrqfle, wdien a task executes putO on a full 
queue where the queue tail is in WMODE, then fliat task will be suspended until the queue is no 
longer full. The inodes of a queue's head and tafl need iK>t be the same. 

Similarly the maximum number of o^ects whidi can be on a queue can be by idmaxO and 

changed by setmaxO. Decreasing the maximum bdow the current number of objects on the queue is 
legal. Doing this simply implies that ik> new objects can be put on the queue until the queue has been 
drained below the new limit 


The Task Library 
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QheadsrdcottntO returns the current number of objects in a queue, and qtailsrdspaceO returns die 
number of objects which can be inserted into a queue before it becomes fulL 

QheadnputbackO puts its ai^gument bade at the head of the queue, diat is 

qhead q^(f»CDE,10) ; 

abject* oo - q^.getO ; 

. putback (oo); 
oo - q^.getO; 

will assign the same object to oo twice. PutbadcO has proved to be a useful function in many systems 
in the past, and it also allows a queue head to c^)erate as a stack. When puttradcO is used, the task 
executing it competes for queue ^ce with tasks uang putO on the queue's taiL A putbackO to a full 
queue causes a run time error in bodi EMODE and WMOQE. In ZMODE it returns NULL. 


More about Tasks 


When a task is created it can be given duee arguments. The first is a diaracter string pennter which is 
used to initialize die class task variable t_naine. Ihis name can be used to provide more readable out¬ 
put and does not affect the behavior of die task. The strir^ denoted by the pointer will not be copied. 
The t_name is used by die debugging aids and error reportii^ functions described bdow. The other 
two dass task arguments are tuning parameters and w^ be described below. If an argument is NULL 
a ^tem defoult will be used. For example, we could have given each Server task a name like this: 


class Server : public task 
{ 

Server (char*, q^iead *); 


1 ; 


void Server::Server (char* name, q^iead* in) 

: (name) // argument for Server's base class task 
( 

// ... 

1 


Server n!y_nan«e_is__fred(*fred", qjhp); 


Taskssleep(objec^ sO) suspends the task unconditionally without spedfyir^ what is supposed to 
cause it to be resumed. 

If an argument is given to taskssleepfob ject* aO) which is a pointer to a pending object, 
the task will be /emembered by the object, so that after it is no longer pending, the task 
will be resumed. 

TaskscancelO puts a task into the TERMINATED state and sets the return value just like resultisO. 
However, cancelO does not invoke the scheduler so that one task can terminate another widiout losing 
control itself. 
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The pointer 


task* thlstask; 

denotes the cuirendy active task. If no tasks have been created its value is a It is fll^al to assign to 
diistask. The use of ttiistask enables the dass task functions to be used from external functions 
without explicit passing of the current task's Oiis pointer. 

The pointer^ 


task* taskjchain; 

is the start of a chain of all tasks. In dte following loop t points to every fagk in turn: 
task* t; 

for <t-task_cbaln; t; t-e->tjne*t) ; 

It is not possible to have only one task. Therefore, when foe first task is created in a program another 
task is iir^idtly created. Its name is main atul its code is foe original mainO function. It can be 
suspended and resumed like any other task. Please remember that a return from mainO terminates a 
C program. If the "main" task should be terminated when there are other «diich should be left 
running, then resultisO can be used. For examprie, 

thistask->cesultis(0); 

can be executed in mainO. The program %vill foen run on until no more tasks are or can becom e RUN¬ 
NING. 

It is illegal for a task to returru Always call resultisO instead of retain, and never just "dix^ out of 
the bottom" of a task. Unless a tadc contains an infinite loop so foat it will never terminate a 
call of resultisO at the end of its body. 

The task system does not provide a gaiha^ collector. It is left to foe programnter to ensure foat 
pointers to deallocated store are not used. 


Waiting 


Functions like sdiedrzesultO, qheadi^etO, and qtailspuK) eadt provide a way of waiting for one sin¬ 
gle specific event to happen. More geiteral facilities ate sometimes ne eded 

When an object must be waited for, we say it is penJhg. For example. 

■ A queue head whose associated queue is empty is pending because if a task ca Ms 
getO for it. the task must wait until some other task puts some data in the queue. 

■ Similarly, a queue tail whose queue is fun is pending because a putO must wait, 
and 

■ A task that has not terminated is pending because its result is not available. 


The Task Library 
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Each class derived from object may have its own definition of the virtual pendingO 
function. An object may have several operations that could suspend the calling task, 
but it can have only one definition of pendingO. Therefore (for example} it is not possi¬ 
ble to combine a queue head and a queue tail into a single ot^ect, because the former 
is pending when its queue is empty, and the latter when its queue is fun. New kinds of 
objects, with new kinds of interaction can be added to the task library, with the funda¬ 
mental requirement being a definition of pendingO for the new datatype. 

Taskrwaitfobject*) provides a way of waiting on an arbitiaiy oi^ect If the argument points to a 
pending object, ttte calling task will be suspended until dte ol^ is no loi^ pending. If the argu¬ 
ment is not peiuling the caller will not be suspertded at aD. Fte exan^^, if taskp is a pointer to a task 
then 


wait(taskp); 

will suspend the task executing it untQ the task denoted by taskp finishes. 

Each class derived ftom dass object which is ever going to be "waited <m" must have rules ^jedfying 
under which conditions a task executing a waitO fix’ it will be resumed. The rules for class task, 
qhead, arui qtail have been stated. 

The conditions for wakeup are reflected in state chai^ in the olqects, and are not just transitory 
unrecorded signals. F6r example, if a task executes a waitO for a rton-empty qhead it will immedi¬ 
ately continue, that is the condition for returnir^ from a waitf) for a qhead is that the queue is non¬ 
empty, not a brief state change from empty to non-empty. Rules of this ^^>6 simplify programnung 
considerably by dimiruiting race conditions. 

When the state of an object changes from pending to not pending. objecbulcxtO must 
be called for the object. This function chariges the state of all tasks “remembered” by 
the object from IDLE to RUNNING and puts them on the scheduler's run^chain. 

Thus all such operations should be member functions of the object's class or a related 
class. For exanple. in qtailsputO. if the queue was empty, a can to alertf) is made for 
the associated queue hea^. If it was possible to put an object on a queue wtthout cal- 
Eng a mentoer function, then there would be no guarantee that alertO would be caHed. 

The functions taskswaitvecO and taskswaitlistO suspend a task waiting for one of a list of objecte, for 
example to wait for rttessages to arrive on one of a number of queue heads. Waitlist(objectf ~.) 
takes a list of object pointers terminated by a zero as argument; for example: 

^lead* ql; 

^lead* q2; 

// ... 

short idio * waitlist (ql, q2, 0); 

will su^iend foe task eitocuting it until either ql or q2 is ruxi-empty. If afoer is non-empty when 
waitiistO is called foe task wiU contiirae inunediately. 

The value returned is foe position in foe list of the ol^ that caused the return from foe wait, that is 
if q2 caused the task to resume the value 1 will be assigned to wfoo. Positions are numbered starting 
from 0. WaitiistO can take any number of arguments. The degenaate example 
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waitlist(0) ; 

causes unconditional suspension of the task executing it without any guarantee of later resumption It 
is equivalent to sleepO and waitfO). 

Please note diat one should not assume that because waitUstf) returns a particular value indicating one 
obj^ as the cause of resumption none of die other objects are "ready." Ilie value returned by 
waidistO only indicates what is known to have happened, and it does not exdude other independent 
px>ssibilities. ^ 

However if waidistO indicates a particular object, that ot^ is guaranteed to be 
“ready," because waidistO does not return until the object is no bnger pending. 

Because every dass in the task system allows non-blocking examination of the conditions whidi might 
lead to suspension using the three wait functions, die value returned by waidistO can always be 
ignored. The infonnaticm it conveys can always be obtained by direct iiMpiiiy. In many cases, how¬ 
ever, the value returned can be trusted and used to write sirr^ler, more efficient programs. 

WaitvecO, a variation of waidistO. takes the address of a vector holding a list of otnect pointers. F6r 
example: 


object* vecll - { ql, q2, 0 ); 
short who « waitvec (vec); 


is equivalent to the previous example. 

System Time and Timers 

The long variable dock measures simulated time. It is initialized to zero. It is to assign to 
dodc. 

Task=del^r(int) suspends a task for a specified time. That is, 

long t > clock; 
delay (n); 

actualjdelay * clock-t; 


will assign the value n to actual_deU^. DelayO is useful for re^nesenting service delays in simula¬ 
tions. While a task is delayed in diis way its state is still RUNNING, but it will not be adected by tiie 
actions of other tasks except if cancelO or preemptO is used on it DcU^fn) makes an IDLE tas k 
RUNNING so that it will start executing at time docks-n. 

TaskcpreemptO makes a RUNNING task IDLE and returns the number of time units left of its dday. 
Applying preempK) to an IDLE or TERMINATED task causes a run time error. This function b use- 
fd when tasks are used to represent processes in a system %vitti preemptive sdiedulit^ and dday 
times are used to represent the time used by executi^ processes. The value returned by preemptO 
allows ^ preempted task to be re-started with a new delay time which is a function of the dday time 
at the time of preemption. For example: 
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int tiae_left •« other_task->preenpt () ; 
// ... 

other task-xielay (tijne_left+10) ; 


A timer provides a fodlity for implementing time-outs and odter time dependent phenomena. 

Cia«ts timer has this dedaration: 

class tiaer : public sched { 
public: 

timer (int) ; 

-timer () ; 

void reset (int); 

void print (int, int ^); 


A timer is quite amilar to a task with a constructor consisting of die sin^ statement 


delay(d); 


that is. when a timer is created it simply waits for die number erf tune units given to it as its argument, 
and then wakes up any tasks waiting for it. 

A timer's state can be eidier RUNNING or TERMINATED. This state can be inspected by uang 
schedrrdstateO. 

A c om mon use of timers is to wait for a task and a timer. For example, one can wait for the comple¬ 
tion of a handling a simulated input operation and also on a timer. The timer ensures diat the 
waiting task wiU eventually be resumed even if the iiqnit operation is never oompleted:^^ 


timer* tt - new timer (15); 

short res - waitlist (io_ptr,tt,0); 

siritch (res) { 
case 0: 

/* normal oonpleti«i of i/o */ 
break; 

case 1: 

/* time out occurred */ 


default: 

1 


break; 

error (IMPOSSIBLE); 


Schedrresult and schedscancelO have the same use and effects on timers as on 
tasks. Since there is no timetcresultisO, the value returned by sdiedaesaltO is 
undefined for a timer unless cancelO was used. 
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TimeirresetO re-sets tfie timer delay to the value of its argument This makes repeated use of timers 
possible. A timer can be zesetO even when it is TERMINATED. 

A unit of simulated time can be used to represent any unit of real time. Only delj^) causes the clock 
to advance. 


More About Queues: Cutting and Splicing 

One of the most convenient and powerful ways of using tasks involves defined U> do a transfor¬ 
mation on a data streanL Such a task is called a filter. It reads its ir^t from one queue and writes its 
output onto another queue. Tasks at the "other eiKls" of these queues tend to view these queues plus 
the filter as one entity. The data source simply sees an output queue diat is being emptied at sonte 
rate, and the task at the receiving erui sees an iiq>ut queue being filled. In other words, a task sees 
only its input aiwl output queues aiul cares little about die 'internal organization" of the progra ms 
that operate on the other aids of those queues. 

For example, one task could produce a stream of lines of characters, diat is objects of Line, and 
another expect an ir^t stream consisting of words, that is objects of Ha<8s Word. A filter diat handles 
the conversion could be defined and used like this: 

class Line tojHOzd : task 
{ 

public: 

Linejto_wocd(qhead*, qCail*); 

Word* nesct weed (Line*); 

>; 


Linejbojwocd: :Line tojwocdf^iead* in q, qtail* ouC_q) 
{ 


Line* 

1; 


Word* 

w; 


for(;;) 

{ 



1 - (Line *) in_q->get(); 

I 

while(w 

- nextjwordd)) out_q->put((object *)w); 

qhead* 


line_q - new qhead<1tCOE,10) ; 

qtail* 


wozdjq • new qtail (itCI^, 50); 

Producer* 

prod * new Producer (line_q->tail ()); 

Cmsunec* 

cons - new Constsner(wozd_q->faead()); 

Linejtojword* 

filt • new Linejtojwozddinejq, wozdjq) 


In this way the filter filt is programmed into the path between cons and prod using two queues to 
separate flit's input from its output. 
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This is a fairly static use of a fUter. Often one would like to insert a filter into an existing data path. 
For example, a macro-based text formatting program could be organized as a sequetKS of filters — 
each doing its small part of the conrunon task. Rrst some filters re-anange the input into a form suit¬ 
able for the formatter proper, then the "input independent" formatter does its job producing output of 
a standard form, and last some output filters adjust this output to a form suitable for physical output. 
The fagif filt is an example of such a filter. In th^ scenario it would be useful to have ead\ macro 
defined as a filter which foe formatter proper mserts just in front of itsdf ufoen foe macro expansion is 
needed and which removes itself when it is not needed any more. Assuming foat data streams are 
represented by queues, fois can be adiieved by using foe class qhead functions cutO and spliccO. 

When foe task f ormatter recognizes a call to the macro "loo" it creates a new task of dass Macro to 
handle a maao of type FOO and diverts its own input through it This is done by first "cutting" the 
input queue to create a place to insert the new filter, and thai aeating foe filter giving it the new 
qhead and qtail as argunnents: 

^^lead* newhead - inputjqueue->cat (); 

qtail* newtail - input_queue->tail () ; 

Macro* £ new Macro (E^, newhead, newtail); 


QheadccutO ^lits the queue to which it is applied into two. Newfoead, foe pointer returned from 
cuK), denotes foe qhead for the original queue aiwl has the same mode as foe cniginal qhead. The ori¬ 
ginal qhead is now attached to a new empty queue with foe same max as foe original. 

Puts to foe original qtail will foerefore place objects on the filter's input queue, and gets from foe ori¬ 
ginal qhead will retrieve objects from the filter's ouqmt queue. 

The result of these operations has been to insert a filter wifo an input and an output queue into a 
queue without changing the appearaiKe of foat queue to anyone using it, and without halting foe flow 
of objects through foat queue. In our example foe macro expansion filter foo wiU getO foe input 
which would otherwise have gone to foe formatter, interpret it as macro arguments, and ouq>ut foe 
expanded input as its output 

The filter can be removed again by splicing its input and output queues together with qheadnspliceO: 
ne%rhead->splice (newtail); 


SpliceO deletes foe qhead to which it is applied, foe qtail given to it as an argument, and foe queue 
denoted by that qtail If foe spIiceO operation causes an empty queue to beconne rwn-empty or a full 
queue to become noir-fuU all tasks waiting for sudi a state change are resumed. 

Deleting the filter completes foe cleanup: 

delete f; 

Typically a filter would reiitove itself when its task was completed, because foe task foat inserted it 
would not be programmed to be aware of the presence of foe filter it inserted. The sequence of opera¬ 
tions which enables a task to remove itsdf without a trace is: 
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cancel (euiy_value) ; 
delete thls; 

This will work because cancelO does not imply immediate suspension, only a guarantee that the task 
cannot be resumed. 

QtailtcutO and qtailcspIiceO are similar to qhead, but they operate on the other end of the queue. 


Encapsulation 


Passing information between tasks through queues can lead to rather tedious, repetitive (and therefore 
error prone) paddng and unpacking of information into messages. Sinif^ encapsulation teduiiques 
can be used to relieve the programmer of this. For exanqrie, by adding a constructor to the Mes¬ 
sage the server example could be re-wiitten thus: 


class Message : object 
( 

public: 

int cjopecation; 

int r_argl; 

int cjac 92 ; 

qtail* r_reply; 

Message(int c^, int al, int a2, qtail* cp) : 
rjoperation(op), rjargl(al), 
c_acg2(a2), r_reply(rp) {) 


Message* mess; 

rq->put(new Message(FLOS, 1, 2, rplyjto)); 
mess « (Message *) cply.getO; 
if (ness->c_operation « ERBi^) error (); 


Furthermore, because the message queues obviously are nneant to hold only Message objects a ^>ecific 
message queue could be defined atKl used: 
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class Mq^tead : qhead 
( 

public: 

Message* get() ( return (Message *) ^tead: :get (); ); 

1 ; 


class Mqtail : qtail 
public: 

int put (Message* m) { return qtail::put (m); ); 

}; 

The use of MqtailsputO ensures that only dass Message obiects are put on the queue, and no type cast 
is needed when Message olqects are taken from the queue udng MqheadigeM). For example: 

mess - rply->get(); 

Because the body of MqtailsputO is present in the dass Mqtail, dedaration caUs of MqtailsputO will 
be expanded inline. This ensures that using a Mqtail is no less effident tttan using a qtail direcdy. In 
many cases some error handling can also be handled by die derived putO and getO functions. 

An alternative solution is to provide die server dass with functions which handle die packing: 

class Server : task 
{ 

qtail* inp; 

public: 

Server (char*, q^iead*); 
int plus(int, int, Mqtail *}; 
int minus (int, int, Mqtail *); 

1; 


int Server: :plus (int argl, int arg2, Mqtail * rqt) 

{ 

Message* mess; 
int x; 

inp->put(new Message(PL0S,argl,arg2,rq[t)); 
mess - rqt->headO->get 0 ; 

X ■> niess->rj^)eratian; 
delete mess; 
return x; 

1 

so now the server task can be requested to perform services like this: 
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Mqtail qq; 

Server ss(*plus_and_minus", 0, 0); 

int two - ss.plusd, 1, 6qq); 

int ten ss.minus(12, 2, £qq); 


For large programs this style of inter-task communication promises not only increased darity, but ai«y> 
increased efficiency. The message queue interaction may, where necessary, be transparently replaced 
by a specially tailored inter-task communication fadli^. 

These techniques are now widely applied in C++ programming, but when this paper 
was first wrttten, they were new to C. 

Histograms and Random Numbers 


To ease data gathering dass histogram is provided, 
struct histogram 

// "nbin” bins covering the range [l:r] uniformly 
// nbin*binsize — r-1 
{ 

int 1, r; 

int binsize; 

int nbin; 

int* h; 

long sum; 

long sqsum; 

histogram(int«16, int-0, int«16); 
void add(int); 

void print(); 

); 


A histogram consists of nbin bins h(0], ~ hlnbin-l] covering a rai^ [la] of integers. The function 
addO adds oiie to the correct bin for its integer argument The sum of die integers added is main¬ 
tained in sum, and the sum of their squares is maintained in sqsum. If an argument to addO b out¬ 
side the range [la] the range b adapted by either decreasing 1 or increasing r. The number of bins 
remains constant so the size of the range covered by a bin b doubled each time die 5 * 7 ^ of the range 
[la] is. The pzintO function prints out the numbers of entries for each non-empty bin. 

In most simulations some form of random number generation b needed. The generators {vovided 
here are intended to help the developer of a simulation to get started and to provide a paradigm for 
generators of more suitable distributions. 
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class randint 

// unifosn distribution in the interval 
{ 


public: 


1; 


long 

randx; 


randintdong s 

void 

seed(long s); 

int 

drawO; 

float 

fdraw0; 


0 ); 


[0,»«XINT_AS_rLCa.T3 


The foUowing pr^^am shows the use of class landint The ints returned by randinfcdrawO are uni- 
foi^y dismbu^ m the mterval l(klaigest_positive_intJ. The floats returned by randinfcfdrawO are 
uniformly distributed in the interval [0:1]. 


mainO 

{ 

randint ir; 

register i; 

for (i-0; i<100; i++) 

printf(-i-%d £-%f -, ir.draw(), ir.fdraw()); 


Eachobject of da» randint provides an independent sequence of randcan numbers. RandintsseedO 
an be to reimtialize a generator. The dtawO function calls the underiying C library randO) 
Sir? generators for other distributions are easily programmed. Note that erandrdrawO 

calls logo from the math library, so a program usmg it must be loaded with -Im. 


class urand : public raxidint 

// uniform distribution in the interval [low, high] 
public: 

int low, high; 

urand (int 1, int h) { low-1; higirt; ) 
int dzawO { return int (low + (high-low) • 

(0+rarKluit::draw()/MoclOTJ(S_FIXS^ } 


class erand : public randint 

// exponential distribution random number generator 
public: 

int mean; 

erand(int m) { meaimi; }; 
int draw (}; 

}; 
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Impiementation Details 


The following sections contain many implementation-dependent details. The implementation 
described is the UNIX version. In^lementation-dependent information is unfortunately often neces¬ 
sary to allow tuning and ease debugging. 

Task Stack Allocation 

The two arguments mode and stadcsize allow the user to guide foe system's handling of foe t ask 
Their exact interpretation is in^lementation dependent Users who are not interested in in^tementa- 
tion details and/or want a more portable program should set them bofo to zero. The system wiU then 
choose (hop^ully reasonable) implementation-dependent defoult values. 

The stadcsize argumeiU indicates foe maximum amount of stack storage that foe task is allowed to 
use. Using more is an error. It will be expressed in a unit of store (Qpically machine words) suitable 
for stack allocation on foe host system. 

The mode provides additional information. The value SHARED indicates that foe q>ace should 
be taken from the stadc space of foe parent task, foat is foe task which created foe new task. Where 
SHARED stacks are used the active part of the stack is copied to a save area when a is 
su^)ended, attd copied bade when it is resumed. Smee SHARED stsefc locations art not to a 

single task pouters to local varuMes diould not be passed to other tasks. The time needed to sus pe nd and 
resume a task with SHARED stadc is approximatdy proportional to the of g pare actu¬ 

ally used at foe time of suspension. 

If, on foe other hand, foe mode is DEDICATED then a new and separate stack area is allocated, and 
no copying of stack ^ce will occur. 

Scheduling 

Functions of a system dass, krtown as foe scheduler, are invoked as foe result of any hmetion of Ha<c 
task which causes the su^rension of a runnii^ task, and may be invoked by any function from foe 
standard classes described here. The scheduler sdects foe next task to run. When foe scheduler finds 
no more tasks to run, and there are rx> inteiTupt_handleis, it examines foe pointer variable exit fet, 
and if this is non-zero the scheduler will call foe function denoted it ~ 

Whenever dock is advanced the scheduler examines the pointer vaiiaUe dock_fask. If this denotes a 
task, then that task will be resmned before any ofoer task. Ihe dodc_task mu^ be IDLE when 
resumed by the scheduler. The class task function sleepO is useful tcTensure this. 

Debugging and Tuning Aids 

The task system has been designed uitder foe assun^tion foat a typical use of tasks may involve hun¬ 
dreds of tasks and need tuning to achieve an acceptable time-qiace tradeofo The task of debugging 
such a system can safely be assumed to be non-tiivial. 

Classes were used in the in^ementation of the task system laigdy because th^ allow the scope of 
data and functions to be explidtly restricted to the ol^ect to %duch they bdong. This allows better 
type checking of a multi-threaded program than could be achieved by a function-based inplementa- 
tion. The classes vfoidi constitute foe task ^tem were designed to allow quite strong t 3 pe checking 
of programs using them. 
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A number of run time errors are detected by the task system. For example it is illegal to delete a 
queue on which a tstsk is waiting. When such a run time error is detect^ the task ^rstem function 
object=task_ezror is called witit the number of the error and the tiiis pcxnter of the object which 
caused the error as arguments. A list of run time errors appears under "RuiwUme Errors.” 
Task_error() will in turn examine tite pointer etxor_fct and if tius is non-zero call the function denoted 
by it with a copy of its own arguments. CXherwise task_eiioi<) will call the ^tem function exitO 
tvith the error nuixrber as argument. 

When returning from task_exzoz() after executing an eiz<or_lct which returned rafter than usirtg exit() 
the task system will re-try the operation whidi caused the error ([wovided that £izor_fci could have 
affected the condition whidi caused fte error). For exanqile, a puff) to a qhead will be re-tried 
because the user's enror_fct mi^t have eifter caused tiie getO function to be used on fte queue, or 
used chmaxO to allow more objects to be inserted into that queue. 

This error handling mechanism is primarily designed for debugging and it is expected 
that user error functions wiU print some appropriate error message and exit. 

Beware of infinite loops. 

All task ^tem dasses have a function prinff) whidi can be used to print fte contents of tiieir objects 
on stdoub A prinff) function takes an int argument indicating the amount of information to be 
printed. PrinffO) gives the minimum amount of information, piinffVERBOSE) rather more, and 
prinffCHAlN) wiU caU prinff) for olqects on lists associated wift fte objed vrift its own arguments. 
The prinff) argument constants can be combined by the or operator. For example 

thistask->pcint(VERBOSE); 
rainjchain->print (VERBOSE I CHAIN) ; 

will verbosely describe every non-TERMINATED timer and every RUNNING task. For tasks infor¬ 
mation about the run time stack is printed by prinffSTAQO. If ^ variable _hwin is set to a non-zero 
value, prinffSTACK) will also give an estimate of the maximum amount of stiidc space ever used by 
the task, the stack's "hi^ water mark.” For tasks that share a Stack, fte hig^ water mark printed will 
be the high water mark of the most greedy task. For example, information describing stack usage for 
all tasks can be printed by: 

task chaitt->pcint(STACKICHAIN); 


The output of the prinff) functions is implementatiorvdependent and hopefully self-explanatory. 

Overheads and Performance 

The store used for representing a class object in addition to the user specified data is: 


object 

3 words 

timer 

5 words 

task 

18 words + stadcsize 

queue 

15 words (indudir^ the qhead and fte qtafl) 


The times needed to execute some of the task ^em functions are (very) approximatdy: 
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C fXDcedure call return 

1 unit 

task suspend resume 

9 units (usii^ resulK)) 

put 

2 units 

get 

2 units 

wait, waitvec, or waidist 

3 units 


The last four actions can all cause a task to be su^iended. When ttiis happens add 6 units of time. 

For timing results relative to UNIX process switching, see "Extendng the C+* Task 
System tor Real-Time Control." 

The task sjrstem uses about 15K b 3 rtes of store for program and data, but mudi of ttiis is redundant 
virtual function tables that will be diminated in a future version of die C*+ con^nkr. 


The object Class 


The task system as described above is implemented using a lower level of abstracticm ba sed on the 
direct use of the class object Oass object can also be used as a base for odier (user defined) abstrac¬ 
tions, but beware, it is an incrementation tool that is not intended to be us ed direcdy. 

Qass object is a base dass for all classes in dte task system and also die most basic fodliQr for inter¬ 
task communication. The dedaiation of dass object looks like diis: 


class object 
{ 

friend sched; 
friend task; 

©link* 

public: 

object* 
victual int 


void 

void 

void 

victual int 
victual void 

}; 


o_link; 

o_next; 

ojtypeO; 

object 0 { o_llnk-0; o_next«0; ) 

-object 0 ; 

c«nenbec(task* t) { o_link - new olink(t,o_link); } 
forget (task*); // cenove all occurzenoes of task fcom chain 

alert 0; // pcepace IDLE tasks for scheduling 

pendingO; // TRDE if this abject should be waited for 

print (int, int -0);// first azg VERBOSE, CHklN, or SXACK 


The task system implements otqects of TASK, QHEAD, QTAIL, and TIMER. 

Virtual functions make it unnecessary to ever test the type of an otjject. The virtual 
function o_type() is never caOed. 

A task can be added to the set of tasks "remenibered" by an ctoject by executing objedaememberO 
and a task can be removed from this set by executing objecbdotgetO. Executii^ objectsalertO has the 
effect of transferring all IDLE tasks remembered by the ot^ect to the iun_diain and the RUNNING 
state. ” 
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The virtual function object=pending() provides the “glue” that aUows new kinds of 
objects and new communication protocols to be added to the task system. The object 
may have any kind of operation that may cause the invoking task to wait, but it must 
implement its own version of pendingO to tell whether the operation would cause a 
wait. 

A usk can be "remembered" by several objects or several times by tf»e same object without any ill 
effects. ForgetO will insure that its argument is not "remen*ered" any more, and it causes no bad 
effects when used for an object that does not "remember" its argument task. No record is kept of how 
many alertO operations have been executed on an object. AlertO does not cause ar» object to foigetf) 
ta sk? Executing a rememberO does r»ot su^Knd a task. Applying alertO to an object that does not 
remember any tasks is legal, but has vo effect Caveat emptor! 

The functions objecfcrememberO, objectsforgeK), objectrpendingO, and objectsrfertO provide a sim¬ 
ple, efficient, but unstructured arul therefore error-prone communication mechanistrt. 

The declarations for the task system classes can be found in /usx/include/CataskJi on systems where 
it is implemented. 


Run Time Brors 


When an error is detected at run time, task_etror() is called. This function wiU examine err^Jct and 
if this variable denotes a function, that function will be called widi the error number and tiiis as argu¬ 
ments, otherwise the error number will be given as an argument to ptint_^eirorO which will print an 
error message on stdeir and terminate the program. 


E OUNK 

e"onext 

E GETEMPTY 
E~PUTOBJ 

e'putfull 
e"backobj 
e"backfull 
E SETCLOCK 

e"clcx:kidle 

E RESTERM 

e"resrun 

E~NEGTIME 

e"resobj 

E^HISTO 
E STACK 
RESTORE 
E_TASKMODE 
E_TASKDEL 
E_TASKPRE 
E_TIMERDEL 
E SCHTIME 

e'schobj 

e"qdel 

E~RESULT 

E_WAIT 

E_FUNCS 


Attempt to delete an object which remembers a task. 
Attempt to delete an object whidi is still on some chain. 
Attempt to get from an empty queue in E_MODE. 

Attempt to put an object already on some queue. 

Attenq^t to put to a full queue in E_MODE. 

Attempt to putback an object already on soioe queue. 
Attempt to putback to a full queue in E_MODE. 

Qock was norr-zero when setdockO was called. 

The clock_task was i»ot IDLE vdren the dock was advanced. 
Atteiiq>t to resume a TERMINATED tadc. 

Attempt to resume a RUNNING task. 

Negative argument to dela)K). 

Attempt to resume task or timer already on sorrte queue. 
Bad arguntents for histogram constructor. 

Task run time stack overflow. 

No nrore free store — newO failed. 

Illegal mode argurrtent for task constructor. 

Attempt to delete a non-TERMINATED task. 

Attempt to preempt a rron-RUNNING task. 

Attenq>t to ddete a ru)n-TERMINATED timer. 

Scheduler run chain is corrupted: bad time. 

Sched object used directly instead of as a base dass. 
Attempt to delete a non-empty queue. 

A task atterrq>ted to obtain its own res ultO. 

A task attempted to waiK) for itself to TERMINATE 
Internal error — carmot determme the call frarrre layout. 
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E_FRAMES 
E_REGMASK 
E FUEX3E_SIZE 
E^NO HNDLR 
E_BADSIG 
E LOSTHNDLR 


Internal error — cannot determine frame «si 7 e 
Internal error — unexpected register mask. 

Internal error — fudged frame too big. 

No handler for the generated signal. 

Attempt to use a signal number that is out of range. 
Sigital haiviler irot on duin. 


A Program using Tasks 

finclude <task.h> 

/* trivial test exanple: 

nake a set of tasks idiich pass an object round between themselves 

use printf to indicate progress 

NARNIMG; this program sets an infinite loop 

*/ 


class pc : task 
{ 


1 ; 


pc (char*, qtail*, qjuead *); 


pc::pc{char* n, qtail* t, qhead * h) : (n,0,0) 

{ 

printf ("new pc (%s, %d, %d) \n",n, t,h) ; 
while (1) { 

object* p - h->get(); 
printf("task %s\n",n); 
t-^ut (p) ; 

} 

} 

mainO 

{ 

qhead* hh « new q^tead; 
qtail* t - hh->tail(); 
q^ead* h; 
short i; 

printf("mainXn"); 

for (i-0; i<20; i++) { 

char* n - new char[2]; /* make a one letter task nama */ 
n[0] - 'a'+i; 
nil] - 0; 

h » new qhead; 
new pc(n,t,h); 
printf ("main ()' s loc^\n") ; 
t * h->tail0; 

1 
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new pc("first pc",t,hh); 
printf ("nain: here *»e go\n"); 
t->put(new object); 
printf ("itBin; exit\n") ; 
thistas)c->resultis (0) ; 
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NOTE 


This section is taken from a paper by Jonathan E Shopiro. 


Abstract 


The task system for coroutine programming %vas one of the first libraries written in C-m- and it has 
served admirably in several applications. It is anall, efficient, and ea^ to use. As part of a robot con¬ 
trol project, it was extended to support real-time contioL The new task library is more robust, more 
easily extendible, aitd more portable than die originaL It is uptvard compatiUe, so diat programs writ¬ 
ten for the old task library can sdU be used. This section documents die new features and the internal 
structure of the revised system, and is intended for users of the task fitoary and for authors of other 
coroutine ^tems. 


Overview 


The C*+ task library is a coroutine^ suf^xnt S)r5tem for C-*-*-. A task is an object with an associated 
coroutine. The task library includes a scheduler that enables eadi task to execute just when it has 
work to do, and to wait when necessary for ^latever is needed. 

Programming with tasks is particularly appropriate for Mutations, real-time process control, and 
other applications which are naturaUy represented as sets of concurrent activities. A t as k can represent 
a simple part of a complex ^tem, and when die task gains control, it can process its current ir^t 
data, perhaps creating odier data diat will be processed other tasks. It can then rdinquish control, 
waiting for more input or an external event. 

In a program using the C-m- task system, all tasks share die same address ^ce so diat pointers can be 
passed between ta^, and it is ea^ to share common data structures. Also, die scheduler is non- 
preemptive, so that eadi task runs until it e^liddy gives up the single processor, and only dien does 
the scheduler choose a new task to run. This diminates the need for locks on shared data (which 
would be recpiired if preempt i ve sdieduling or multiple processors were used) and allows task¬ 
switching to be accomplish^ widi low overhead, but requires the programmer to be careful diat no 
task monopolizes the processor. 

The rest of this section is an overview of control flow in die task ^tem along with a brief note on 
task system performance. The section "Real-Time Extensions" describes die interrupt handler fla« 
and how it can be used to provide real-time response to external events. Familiarity widi C-m- is 
assumed. 

The Structure of the Task System 

Control in the task ^tem is based on a concept of operations which may succeed immediately or be 
blocked, and objects^^ which may be ready or jxnding (not ready). When a task executes a blodciiig 
operation on an object that is ready, the operation succeeds immediatdy and die task continues run¬ 
ning, but if the object is pending, the task waits. Control then returns to the sdieduler, i^ch diooses 
the next task from the run chain, a list that contains all the tasks that are ready to run (not waiting or 
terminated). For example, a queue head is ready when the associated queue has data, and get (which 
extracts an item from the queue) is a blocking operation for queue heads. Similarly, put is a blocking 
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operation for queue tails, which are ready uiUess the a<c<viatPfl queue is full. 

Each different kind of object can have its own way of determining whether it is ready or not, which 
makes it easy to add new capabUiHes to the system. On the other hand, eadi kind of object can have 
only one criterion for readiness (although it may have several blocking operations), so it is not possible 
for one object to act as both a queue head and a queue tail, for example. 

Each object contains a list (the rananber chain) of Ae tasks that are waiting for it. When any operation 
changes the state of a pending object so that it becomes ready, those tasks are moved to the run drain; 
this is called an alert. Thus Ae cycle is: a task runs until it blocks; it is saved on the remember chain of 
one or more pendmg objects; some oAer task or an mtemipt alerts the object; the original task is 
moved to the run dram; eventually the task runs again. 

Task System Performance 

The fundamental operations of the task ^tem are task creation and task switching. In order to make 
a meaningful evaluatitm of tfieir performance, equivalent programs usii^ tasks and UNIX Operating 
System processes were written. These programs are given under''Example Programs." EadiofAe 
first pair of programs (tcreate.c and ucreatex) repeatedly creates rraw trivial ^acVrc (processes) and 
waits for Aem to terminate. Each of the second pair of programs (tswitduc artd uswitduc) creates a 
single child task (process) and repeatedly exdranges control wi A it through a pair of seitraphoies (see 
under "Semaphores") m the task verson, and through UNIX sgnals m Ae process version. The pro¬ 
grams were run on a SUN 3/280 under 42BSD, using the free store allocator (mallocd from NmA 
Edition UNIX, which is much faster than the one supplied wiA 4.2BSD. The results were that tcreate.c 
was 37 tinras faster than ucreate.c, and tswitduc was 10 times foster than uswitduc 

It is important to note Aat Ae task ^em and the UNIX Operating System are not equivalent and 
that the results of these perfbrrtrarKe measurements do not iirq)ly that Ae task system is 23.5 times 
better than UNIX. Among Ae significant differences between tasks and processes are Ae following. 

■ A set of tasks runs as a sin^e UNIX process. The task ^tem relies on Ae UNIX Operating Sys¬ 
tem for I/O, mentory mairagerrrant, etc. 

■ Tasks share an address space, while proce^ have separate address spaces. This means that 

tasks can share data by siiiqdy passing pomters, while processes must go throu^ one of several 
much more complex and expensive p>rocedures to share data. By the same token, can 
interfere wi A each other as easOy as they can cooperate, while errant processes usually kill orUy 
themselves. 

■ The task ^em can support two or three orders of magnitude more concurrent tasks (espedally 
WiA the SHARED option; see 'Task Switching") than Ae UNIX Operating System can support 
processes. It is not uncommon for a simulation to require thousands of ta sks 

The memory required for the task system is about 14/XX) bytes for code and data, plus about 70 bytes 
per task, plus stack storage for each task. By default ead» tadi has its own stack buffer wiA a default 
size of 3000 bytes, but tasks can share a stack buffer and then storage is required orUy for the active 
stack of ead» task (typically 50 to 100 bytes). This option is very useful for applicatiotts wiA 
thousarvls of tasks, (t^ieues occupy 60 bytes (indudmg bo A head and tail) |dus the size of vAatever is 
stored on Ae queue. Lists of ta^ are maintained in various {i^ces, for example Ae run chain and 
remember chaitts; each occurrence of a task on a list adds 8 b)^ to Ae total memory requirement 
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Real-Time Extensions 

The application that motivated this woric on the task system was a control system for two robots 
operating in the same workspace. The most important requirement of diis application that was not 
fulfaied by the oiiginal task system was the need for tasks to wait for external events. Fbr example, 
after a motion command was sent to a robot, the task that sent the command needed to wait for the 
interrupt that was generated by the robot hardware when fte command was complete or had foiled. 

A related requirement of some real time systems is to re^xmd to external events in a timely maimer, 
for example to retrieve data from an unbuffered external device. Also, in the original task system, the 
scheduler would exit when the run dudn was empQr. This is inappropriate in a system that is 
intended to re^nd to external events because some task might become runnable after an interrupt 

Hardware interrupts are handled differently by different machines and operating systems, so tfie inter¬ 
face to the task system must also vary. For didactic reasons, Ae veraon described here is for the 
UNIX Operating System using agnals as interrupts, but it should be dear how to adapt it to ofoer 
enviroimnents. 

In the task system events that can be waited for are r epre s e nted by instances of object or derived 
dasses. When the function objectsalertO is called, dm tasks that were waitii^ for that object are made 
runnable. A natural solution to the problem of waiting for external events was to define a new kind of 
object to rei»esent external events, and when such an event occurs^ to caU objectalertO fm the 
appropriate object. These objects are called interrupt handleis. 

class Incemjpc_handler : public object { 

int id; // signal or inte rnet nunber 

int got_intern^; // an intern^ has been reoeived but r»t alerted 

Interrvpt^handler *old; // previous haztdler for this signal 
virtual void interrupt () {}// runs at real t-inw* 

public: 

int pending 0; // FALSE onoe after intermit 

Intemyt_handler (int sig^num); 

~Interrupt_handler () ; 

1 ; 


After an interrupt handler is created, a task can wait for it, exactly as for any other object When foe 
interrupt occurs, foe handler's intenuptO function will be executed imirtediately, or rafoer, as soon as 
the operating system can route foe interrupt to the process. When foe interrupt function returns, con¬ 
trol will resume at the point where the current task was interrupted. 

At the next entry to the scheduler, when foe currently running task Modes, a special task, foe interrupt 
alerter, will be sfoeduled. This task alerts foe handler (aitd any other handlers that have received inter¬ 
rupts since it was last scheduled). Thus the waitiitg task becomes runnable. As long as any interrupt 
haiuller exists, foe scheduler will wait for an inierrupt, rather foan exiting when the run chain is 
empty. The pending function for an interrupt haitdler always returns TRUE except the first time it is 
called after an interrupt occurs. 

Intenupt_handlei::interrupt() is a null function, but since it is virtual, the progranurter can spedfy the 
action to be taken at interrupt time by simply defining an inteiiupK) fuivrtion in a derived from 
Intemipt_handler. An example is given under "Interrupts." In this way real-time response can be 
obtained without resorting to a preemptive, priority-based scheduler which would be more coiiq>lex 
and less efficient, and would require locking of shared data structures. 
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Avoiding Interference 

Whenever shared data structures are manipulated concurrent processes, there is the potential for 
interference, where one process is in the middle of modifying a data structure and another process 
accesses it arwi finds it in an invalid state. Segments of code drat access shared data structure are 
called critical regions}* If more than one process can be in a critical region at one time, there is a poten¬ 
tial for interfereiKe. 

Interference is ea^ to avoid in the task ^em, because of the iron-preemptive nature of the ^heduler. 
There are only two ways in which interference can arise: a task switch occurring within a critical 
region, or an interrupt routiire that accesses shared data. 

It is alrrrost always possible to rvrite code so that no operation that could cause a task to block is inside 
a critical region. The style of programming where coroutines share information by sending messages 
to each other in the form of objects on queues fypicaUy leads to programs where there are no shared 
data structures or critical regions at all. Even if coroutines must share access to a data structure and 
alternately modify it, no problems will arise if the routines that do the modification refrain from opera¬ 
tions that could cause the task to block. A properly modular program will generally satisfy this 
requirement without any extra effort 

Semaphores 

If, for some unusual reason, it is necessary to put an operation that could cause the task to block in a 
critical region, then the affected data structure should be protected by a semaphore, which will allow 
only one task at a time to access the object The following example code outlines this tedmique. 


class Myjdata ( 

Senephoxesema; 
// usee data 


public: 

void lockO ( setna.wait 0; 1 
void unlock0 i sena.signal0 ; 1 

IfyjdataO : sanad) i ... } 

); 


// see note 


Each critical region must begin with a call to MyjJataslockO for the object to be accessed, and end 
with a call to My dabumnlockO. This will ensure ti«t no interference occurs, even if the operations in 
the critical region cause the task to block. 

The implementation of semaphores using the task system is ca^. 
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class Semaphore 
int 

public: 


int 

void 

void 


public object { 

sigs; // the number of excess signals 

Senephore(int i -O) ( sigs - i; ) 
pending 0 { return sigs <- 0; ) 
wait 0 ; 

signal 0 { if (sig3++ — 0) alert(); ) 


void 

Semaphore: :%iait () 

{ 

for (;;) { 

if (—sigs >- 0) 

rettim; 

sigs++; 

thistask->sleep(this); 

) 

} 

Semaphores are useful tools for building other kinds of ^duonization besides mutual exclusion. For 
example, whenever one task wants to wait for an operation to be comf^eted by another task, it can 
wait on a semaphore. 

interrupts 

The other case where interfereiKe can occur is a little more convex. The intezzupK) routine of an 
Interrupt_handler can be executed at any time, and it would be contrary to the reason for its existdice 
to lock it out. The tirechanism that alerts the hartdler after die interrupt has occurred is carefuUy 
designed to be safe from interference, and sometimes the alert is all that is necessary for an applica¬ 
tion. If it is necessary to gather data from an external device immediatdy after an interrupt occurs, 
but the interrupts do not come in rapid succession (for example, die next interrupt won't occur until 
after the device is reset), the interrupt routine can save die data and the task that is waitir^ for the 
interrupt can process the data before resetting die device. In diis case even though the data is shared, 
the interrupt routine cannot access the data at the same time as the task. 

Sometimes, however, it is necessary to handle interrupts that can come in rapid succession, with a 
requirement to gather data at eadi interrupt, so that several interrupts may occur before die task diat 
will process the data can be scheduled, and mote interrupts may occur even while the task is running. 
This problem is best handled by establishing a queue of the interrupt data records. Then the only 
shared data between the interrupt handler and foe task proce s s in g die data can be the queue head and 
tail pointers, whidi can be atomically ufidated. In die foUowing toy example, the interrupt routine 
records the value returned by an arbitrary function, get_data(), eadi time the signal SIGD^ is sent A 
waiting task is then sdiedul^ and prints all accumulated data. 
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class Delete_handler : public Interrxipt handler { 


void 

interrupt (); 


int* 

localq; 

// data buffer beginning 

int* 

loccd.qjend; 

// data buffer end 

int* 

localqjh; 

// queue head 

int* 

localqjt; 

// queue tail 

int 

getX(int£); 

// the next item, if any 


Delete_handler (unsigned local_g_size -5); 

*'I>elete_handler 0 ( delete [localq[_end - localq] localq; } 


The delete handler (so called because SIGINT is normally sent when the user presses the delete key) is 
an interrupt handler that maintains a local queue of data. Its interrupt function will put data on the 
local queue, using localq_t, the queue tail pointer, aiul its getXO fuirction is used by a task to retrieve 
the data. 

Deletejharrdler: :Delete_handler(urrsigned localjqjsize) 

(SIGINT) // base class oonsbructor arg 

( 

localq_t - localqjh - localq - new int [local q^sizel; 
localqjend ■ Slocalq [ localjqjsize ]; “ 

1 

The constructor initializes the local queue. The size of the local queue determines how many inter¬ 
rupts can be awaiting processing. 

void 

Delete handler::interrupt() 

( 

register int* p - localqjt; 

*p - getjdataO; 

if (++p — localqjend) p - localq; 
if (p !« localqji) 

local q _t • p; //no overflow 

else error ("Overflow") ; 

) 

The interrupt function assumes that localq_t points to an available slot in die queue and puts the real¬ 
time data there. It then diecks for overflow and updates localq_t to point to the next available slot if 
it's okay or calls an error function otherwise. 
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int 

Delete_handler::getX(intfi ans) 

{ 

register int*p - localcj_h; 
if (p — localq_t) 
return 0; 

ans - *p; 

if (++P — localqjend) p « localq; 
localq_h - p; 
return 1; 


The function getXO assigns the next datum to its argument and returns "1," or returns't)" and leaves 
its argument alone if no data is available. A call to getXO may be interrupted, but it has been 
designed so drat no corruption of the queue will result. 


class Oelete_printer : public task ( 
Delete_handler*handler; 

public: 

Delete_printer0; 

); 


Delete_printetO is a task that will create a Delete_handler artd print whatever data is received. 


Delete_printer: :Delete_printer () 

: handler (new Deletejhandler) 

{ 

for (;;) ( 

tiait (handler); 
inti; 

while (handler->getX(i)) 
cout « i « "\n"; 

1 

) 


Note that each time the printer task is scheduled, it prints all the available data from the delete 
handler. 

Implementation Details 

The approach taken was to minimize the impact to die sdieduler and to iscdate as mudt as possible 
the machine and operating system dependent parts of the im{^ementation. There is a system- 
dependent function, sigFund), whidi catdtes each signal for which an Inteizupt_handler exists. When 
the signal is sent, sigFoncO caUs the appropriate interrupK) function. It then atomically puts the 
address of a dedicated alerter task in a static, private cell of the scheduler and rearms the signal and 
returns. At the next entry to the scheduler, diat cell is checked and if it is non-zero, the alerter task is 
scheduled. The alerter task alerts all pending interrupt handlers and returns to the scheduler. Tasks 
that were waiting for interrupt handlers are then eligiMe to run. 

The other ^tem-dependent parts of the implementation are the constructor and destructor for class 
Interrupt_handler. Its constructor takes the signal number as argument (it might be an interrupt vec¬ 
tor address in another system). If some other interrupt handler already existed for that signal, it is 
saved (and alerted if it was pending), and otherwise the UNIX system function signalO is called to 
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assodate sigFuncO with the signal. The destructor undoes the action of the constructor, restoring the 
previous signal routine if necessary. ' ® 


Example Programs 


tcreate.c 

The following program repeatedly creates a task and waits for it to terminate. It would be possible to 
time creation of new tasks without waiting for them to termiiuite, but because of the limited number of 
processes that can exist under the UNIX system, the corresponding UNIX system program would fail. 

♦include "task.h" 

class Child : public task // user task declaration 

{ 

public: 

^ Child(int); // task constructor declaration 

Child::Child(int i) // user task constructor definition 

: ("Child") // argument to base class constructor 

resultis(i); // terminate task execution 


mainO 

{ 


} 


for (register int i - 10000; i- 

Child* c » new Child(i); 
c->result 0; 
delete c; 

1 

thistask->resultis(0) ; 


) { 


// create a task 
// wait for it to terminate 
// clean up 

// exit from main task 


ucreate.c 

The following C program repeatedly forks a UNIX process and waits for it to terminate. 


mainO 

{ 


} 


register int i; 
for (i-10000; i—; ) 

if (forkO — 0) 
exit (0); 

else 

wait((int*)0); 


// child process 
// parent process 
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tswitch.c 

The following program uses two semaphores (described under "Semaphores") to alternate control 
between a parent and child task. 

•define K 10000 
•include "task.h" 

class Child : public task 
{ 

public: 


Seiraphore senal; 

Semaphore seiia2; 

Child::Child!) 

: (-Child") 

{ 

for (register int n - K / 2; n 
senal.wait () ; 
senia2. signal () ; 

} 

resultis(0) ; 

) 

main(} 

t 

new Child; 
semal.signal 0; 

for (register int n » K / 2; n—; 
sema2.wait () ; 
semal.signal(); 

) 

thistask->resultis(0) ; 

) 

uswitch.c 

The following C program uses a UNIX system signal to force alternation between two UNIX ^tem 
processes. The program is a little strange in that its main routine coitsists of an infinite loop of pauseO 
calls. Urxfortuiuteiy the utility of wait() and pauseO for signal handling is limited because it is always 
possible that a signal has been received just as the waiK) or pauseO is being executed. 


// send the first signal 

) { 

// wait for a signal from Child 
// send it back 


// wait for a signal from main 
// send it back 


// for signals from main to Child 
// for signals from Child to main 


♦include <signal.h> 

•define KICOOO 
int otherpid; 

int received; 

int child; 

VO LG. 

sigO /• signal-catching routine, called •/ 


The Task Library 


2-35 





Extending the &m- Task System for Real-Time Control 




1 


/* when a signal is received */ 

signal (SIGTERM/ sig); /* arrange to catch the next signal */ 

received++; 

if (child it received >- K/2) exit(); 

kill (otherpid, SIGTERM); /* send it hack *f 

if (!child && received >- K/2) exit(); 


nainO 

i 

signal(SKSTERM, sig); 
if ((otherpid - forkO) — 0) { 
otherpid « getppid () ; 
child 1; 

kill (otherpid, SIGTERM); 

) 

for(;;) 


/* arrange to catch the signal */ 
/* create the child process */ 

/* get parent process id */ 

/* this is the child */ 

/* send the first signal */' 


real timei.c 


In addition to the robot application, ^rstem was implentented on the UNIX Operating System 
using signals as interrupts. A dass Real_timer, modelled on the origiital timer was built. 


class Realjtiiner : public ^ject { 

friend class Alarm_handler; 

int state; 

long tine; 

void insert (int); 

void remove (); 

void resume (); 

public: 

Real_timer(int); 

-Real_tijner () ; 
int pending 0; 

void reset(int); 

void print(int, int -0); 

}; 


// ROMNING, IDLE, TERMZMAXED 
// initially delay, then alarm time 
// put on chain 

// remove from chain s make IDLE 
// called idien time is \ip 


Instead of simulated dock ticks, dass Real_timer measures time in seconds. It is based on the follow¬ 
ing handler for the alarm signal and a task that maintains the list of unexpired Real instances. 


class Alarmjhandler : public task ( 
friend Realjtimer; 

Realjtimer* chain; 

Intem^_handler* bell; 

void add_tiiner (Real_tiiner*); 

void remove_timer (Real_tiiner*); 

public: 


Alarm handler!); 
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I; 


Alann_handler alann_handler; 11 the only Instance 

Alann_handler: :Alaan_handler () 

: (''Alaini_handler"), chain (0) 

{ 

sleep 0; 
for(;;) { 

for (long now - tine (0); chain U diain->tiJie <- now; 

chain * dtealjtioer*) chain->o_next) 
chain->zestaBe 0; // alert the tiaer ~ 

if (chain) ( 

alarm (^iain->tiaie - now); 
wait(bell); 

} else { 

bell->forget(thistask); 
delete bell; 
sleep 0; 

> 

) 

) 

The Intezrapt_handler pointed to by Alann^handlexsbell only exists while Aere are pending 
Real_timer objects. The Alann_handler task nins after an alarm signal, and after alerting any tiineis 
that have exphed, if there are any unesqnred tinners, it resets the alarm and waits. 
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NOTE 


This s«ction is takan diroctly from a paper by Stacey Keenan. 


Introduction 


The C** coroutine libraiy, conunonly known as the task libiaiy aft^ its header file, taskJi, provides 
multiple threads of control within one UNIX ^em pocess. Each thread of control is a coroutine, or 
task, and each task runs until it explicitly gives up the processor; there is no pre-emption. Implement¬ 
ing concurrency requires knowd^ge erf hardware-dependent and compiler-dependent runtime features, 
especially calling sequence and stack feame layout; hence fee libraiy is target-dependent and must be 
ported explicitly to ead» supported conqnler/ixocessor {rfatfonn.^^ The target-dependent parts of fee 
library are isolated in four files. Rdease 20) of fee Lang uay System supirfies the task li br ary for 
the AT&T 3B20, AT&T WE32000 family (e.g., 3B2,3B15), AT&T 6386 WGS and DEC VAX procesrors, 
and the Sun-2 and Sun-3 Workstations (Sun compaers cm Motonrfa 6S000 femily processors). 

This paper describes the implementation of the task library, wife particular emphas is on tadc oeation 
and task switching, where target-dependent code is needed. The existing imfrfementations for fee 3B, 
VAX, and Sun Workstation processors are used as exaiiq>ies.^^ The scc^ of this pa^ is k™«aH by 
the simiiarity of fee runtime modeb supported hy these targets. Targets diverging from these models, 
like mainframe or RlSC-s^le processors, are likdy to present portii^ diffioil tfe* not addressed in feis 
paper. It is assumed feat the reader has access to the source code for fee libraiy. This paper does not 
describe how to use fee ta^ fibiaiy; see "A Set of C++ Classes for Cb-routine SQie Programming" 
and "Extending fee C++ Task System for Real-Time Control" for user^evd information. 'Task 
Switching Fundamentals" provides background needed to understand the workings of the task library. 
"Implementation of Task Switdiii^' describes how fee task library creates new tasks and switches 
among them, indudii^ details about the target-dependent functions swapO and fudge xetomO. The 
final sections discuss source file organization and miscdlaneous hints for porting fee Iforaiy. 


Task Switching Fundamentals 


The C++ task library provides non-preemptive sdiedulmg for tasks. A task runs untO it eiqilicitly 
gives up fee processor to allow another task to run. Typ^y, a task wiU give up fee processor when 
it tries to perform an action feat caimot yet be done, for example, if it tries to put an (feiect on a full 
queue, or to get an object from an empty queue. When feis lu^ipens, the task is put to sleep.** The 
sdteduler then chooses to run the next task on fee ready-to-nm list, 

When a task is put to sleep, or su^jended, the task system must save fee state erf the task so that it 
may be resumed later. On fee targets described here, this involves savir^ fee task's gfark and 
hardware registers, induding the non-volatile registers and fite frame pointer (and the argument 
pointer on some targets). A task switch is the process of saving the state of one task, and restoring the 
state of another. 
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Stack Frames 

Some familiarity with dw C runtime environment and the target implementation of is iteeded to 
understand the details of task creation artd switching. A C function call sets up a new frame for 
the function. A stack frame contains tfte arguntents to the furtcdon, the saved hardware state of the 
calling fuTtcdon, aitd any automatic variaUes used by the functiott. Hgure 2-1 illusttates die 5 *^ 
frames built on the 3B2, the VAX and die Sun*2/3 targets for a function r»n^ with diree arguments 
and saving four registers. These stack frames ate described here to provide a base for later discussions 
on the internals of the task library. 

On a 3B2, the argument pointer (^) points to the start of die arguments to die function, die hame 
pointer (^) points to the start of the automatics of the function, and the st* gk poiitter (isp) points to die 
next availaUesp^ in the stack. The caller's registers are saved between die arguments and the 
automatics. Previous stadc frames can be accessed via die frame pointer The old frame pointer, argu¬ 
ment pointer, and program counter (pc) are always a fixed distance bdow die frame pointer. 
grow up, toward Itig^ier memory addresses. 

On a VAX stacks grow down, toward lower memory, aldiough die figures in this papier will show the 
low memory on top and relative positions on die stadc will be described in terms of the pictures <A g^ 
above means hi^iff in die picture, at a tonver memory address). The argument pointer pcnnts to a 
longword containir^ the number of arguments diat have been pudied on die Arguments are 
pushed in reverse order, so diat the first argument is stored one word below die ap. The fiame 
pointer points to a condition handler, drove idiidi are the automatics of die functkm. The stadc 
pointer points to die last assigned word in the stadc. The word just under die frame pointer contains a 
procedure entry mask, which tdls which regi s ter s were saved in die frame. Saved user roisters and 
the old frame pointer, argument pointer, and program counter are stored between die argument and 
frame pointers. 
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Figure 2*1: Stack Frames on a 3B2, a VAX, and a Sun*2/3 for a Function Taking 3 Arguments and Saving 4 
Registers 
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The stack on the Sun-2/3 Woil^station grows down, toward lower memory. This target has no argu¬ 
ment pointer. Arguments, saved registers, and automatics are aU referenced as offsets from the frame 
pointer. Arguments are pushed on the stack in reverse order, followed by the return pc ainl the old 
frame pointer. The franre pointer points at the old franre pointer. Space for automatics is reserved 
above the frame f>ointer. &ved registers are pushed after the reserved space, and the stack pointer 
points to the last saved register. The 68000 processor has both data (dx) and address (ar) registers. In 
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this example, two of each type are saved. 

On entry, a function first saves all the registers that it mi^t use.^^ On function exit, the same number 
of registers are restored fi*om the register save area of the stack frame. On some targets, like Ae VAX, 
stack frames are self-describing: <me can t^ how many registers are saved in the frame (and i^iere 
they are) from the frame itself (by looking at die entry ma^. Thus, the function return sequence on a 
VAX consists of a single, simple instruction: xet The 36 and Sun-2/3 targets do not have sdf- 
describing stack frames. This means ttiat "return" mstructioits on these targets rteed to specify how 
many registers to restore. When (as happens in the task ^rstem) one needs to restore registers without 
returning fivou^ the iK>nnal return sequence, one can only find out how numy roisters were saved 
on the stadc by lookup at die save instruction at the beginnirig of die function. 

To switch to a new task, the task system needs to know what die new dame pointer (and argument 
pointer on the 36 targets) should be and horn where to restore all the non-volatile registers." The task 
library explicitly saves the frame pointer and argument pointer of the function to be returned to, 
swapO, in die ta^ object as t^ftamep and t_ap. The non-volatile registers are stored in swap's stack 
frame. 

DEDICATED and SHARED Tasks 

Tasks can be of one of two modes: DEDICATED or SHARED. DEDICATED tasks eadi have their 
own stack, of some fixed size, allocated from die free store. SHARED tasks share a sii^e stack, of 
some fixed size. When a SHARED task is dxnit to resume execution, if its stack ^ce is occupied by 
another task,^^ the portion of the stack diat is in use by the odier (suqiended) task b cc^ed out to a 
save area, and die resuming task's stack b copied from ib save area bade into die stadc. Because die 
in-use part of the stack b less than die allocated size of die stadc, the user can save ^albe by using 
SHARED stacks, at a cost in executicxi ^peed. Additional^, some targeb and operatfr^ ^sterns do 
not allow die sbek ixiinter to point into the UNIX process dab segme nt; on th^ systems SHARED 
tasks must be used.^ 


Implementation of Task Switching 


There are two general contexb in which a task switdi occurs: idien a parent task creates a new diild 
task and switches to it, and when a tadc su^iends and the scheduler diooses a new to run. The 
sbeks of both the suspending and resuming tasks lot^ different in each of these situations. Task crea¬ 
tion diffeb from a switdi to a suspended tadc in two ways. HrsL in task creation a runtime environ¬ 
ment for the new task must be set up before die switdi can take (dace. Second, task oeation causes 
the parent task to be suspended and the new tadc to run immediatdy, bypassing any odier wait¬ 
ing on the run chain. b the only case where a task switdi takes place widiout a call to die 
scheduler d> choose the next task to run. These two conte x b are desoibed bdow. 

Task Switches Between Suspending and Resuming Tasks 

In task switches from a suspending to a resuming task (Le., switdies odier dian diose to newly created 
tasks), the function that causes die nmning task to Mock (qheadsgetO in Hgure 2-2) calls taskaslecpO, 
which in turn calb the scheduler, schedsscheduleO. After sdecting die next tadc to run, the sdieduler 
calls bsknresumeO^ for the resuming task. The function taslcaesumeO calls taslcaestaieO, an inline 
function whose purpose b to call the appropriate version of swapO (swap() for DEDICATED tadb, 
sswapO for SHARED tasks) with die appropriate arguments. 
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Rgure 2-2 shows examples of the stacks for a su^^ending and a resuming task, both of type user 
(user_task=user_task() is the constructor and "main" function of the task). Each box in die stack" 
represents a stack frame; the frames for tasksresomeO and tasksrestoreO are separated by a HacKn.^ 
line because tasksrestoreO is an inline function, and therefore doesn't really have its OMm stack frame. 

Figure 2-2: A Task Switch from a Suspending to a Raauming Taak (DEOiCATEO) 
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Switching Between DEDICATED Tasks: swjqK) 

The two swap functions do the real work of perfonning a task s%vilch. Th^ are written in assembly 
language because th^ manipulate hardware registers. The swiq»0 function saves toe state of toe 
su^)ending task Oabded running in toe coder^and restores toe state of the tesumit^ task 
to-run). Saving toe state of the subtending task involves first savii^ all toe non-volatile registeis in 
swap's stack frame, toen saving toe current firame pointer, whkto defines swap's frame, and the argu¬ 
ment pointer, if necessary, in toe sub>ending task's ta^ object, in members t iramep and t “nwH 
swapO overwrites the hardware fiame pointer and argument pranter with the values saved"m the 
resuming task's t_framep and tap. Now the to-run task is runnir^ swj^ returns, restoring all the 
registers that were saved when toe to-run task was subteitded. Note that swap's save is doite on the 
suspending task's Slade, and toe restore is dorte cm toe resuming task's stadc. This is because save and 
restore mstructions are executed relative to toe fiame pointer, which %vas modified in toe m idd le of 
*''^^*^* Figure 2-2 illustrates a ta sk switch on a 3B target. The sw^iO hard%vare fiame and argument 
pointers are shown both before and after the switch. 
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Switching Between SHARED Tasks: sswapO 

The function sswapO is like swaj^, but has additional code for SHARED tasks to copy task gHi/jr; out 
of and into the shared stack area.^ There are three ta^ ttut are rdevant during a SHARED task 
switch: the su^^ending task, the resuming task, and the tadc dtat last occupied dte that d\e 

resuming task now wants to occupy (the target stadc). 'Dus "prevOnStadc" task is often the same as 
the suspending task, but ttiat is not necessarily the case." 

The sswapO functicm first saves all die non-volatfle r e gist er s in its stadc frame, then saves the frame 
pointer (and argument pointer, if necessary) of the su^)ending task in ttiat task's task object, just as 
swapO does. It also calculates and saves the height erf die stack in die tjsize member of the task 
object. Next, it allocates space and copies the contents of die target stadc to that ^ace, i^iich becomes 
"prevOnStack's" save area (pointed to by task member tjsavearea). Next, sswapO copies the resum¬ 
ing task's saved stadc bade from its t_savearea to the stack, and ddetes the ^lace. RnaUy, 
sswapO restores the resuming task's t^framep (and tjtp, if necessary) to be the hardware frame and 
argument pointers, and the resuming task is running. As in swapO, sswapO returns, restoiii^ all die 
registers saved in the resuming task's sswap frame. 

New Task Creation 

To use the task library, the user derives a dass, ndiich I will refer to as user^task, from the 
dass task. The "main" program for die user tadc will be die constructor nscr_tadcniser_taskO. The 
first thing user_taskraser_tajskO does is to call die base dass constructor, tasletaskO. The co n stru cto r 
taskrtaskO initializes the }mvate data for die new task, acquires stack space^ in whidi die task wQl 
run, initializes the stack with die top two frames of die parent task's stack (as illustrated in Rgure 2-3), 
inserts the parent task on the run chain, and switches to die new tadc, which runs immediate. 

Figure 2-3: Creating a New Task's Stack 
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After initializii^ the new task's stack, die parent task continues executicxi in taskstaskO. Notice that 
the parent's stack contains a frame for user_tasksaser_taskO, the child's "main"; the parent task needs 
to sidp over that frame idien it returns from taskstasl^. To arrange this, taskstaskO a function, 
tasksfudge_retum(), to alter taskstask's stack frame so that it returns to iiser_tasksaser task's raiw 
(restoring any registers saved in die skipped frame as wdl). This chai^ to ^ parent'^stadc is 
shown in Figure 2-4 with dotted lines th^^ the nser_tasksaser_task() frame. The fridge letom 
function will be described in detail under "Fudging the Parent Stack." ~ 
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swapO for Chiidren 

When a new task is created, its stack does itot have an instance of swa|>0 on it; taskrtaskO is the top 
frame. It is taskztask's responsS^ty to arrange for die hardware state of ttser_tasksitser_taskO to be 
restored when the child begins execution there. Therefore, taskstaskO saves the frame and argument 
pointers for the diild's taskstaskO frame in the diild's t_framep and t_ap of its task obfecL Then 
taskrtaskO saves all the registers as they were when user_taskruser_faiskO called tas krt askO in a glo¬ 
bal variable, New_task_xegs.^ Getting these registers lig^L ik> matter how many registers were saved 
in user_taskmser_task or taskrtaskO, is a bit trid^. We first copy all the current hardware registers 
into New_task_tegs and then overwrite any of those that are us^ by taskrtaskO %vith diose saved in 
taskrtasl^ fra^ This is done widi a macro, SAVE_CHILD_REGS, %duch calls SAVE_REGSO to do 
the first step, and savc_saved_iegsO to do die second step. 

Then the parent calls taskaesdve, whidi calls sw^O with a NEWjCHILD argument Given this 
argument, swj^) expliddy restores die registers diat were saved in New_task_iegs, instead of restor¬ 
ing the registers saved in the frame. See Figure 2-4. When swapO retunis, the return is effectivdy 
from taslcrtaskO, as that is v^eie die frame pointer points, and then the child task is executing in 
user_taskruser_taskO. On the 3Bs, the assembly language return instruction specifies how many regis¬ 
ters to restore. Because the necessary registers have been res to red from Newjtask_regs, swapO 
restores no registers saved in taskstriskO's frame on its return. The VAX return instruction determines 
the number of registers saved in the frame looking at die entry mask under the frame pointer, 
therefore, when swapO returns, die registers saved in taskstask's frame are restore d . Snce these regis¬ 
ters are die same as those saved by savejsavedjcegsO, save_saved_xegsO is unnecessary on the VAX 


Figure 2-4: A Task Switch to a New Child (DEOICATEO) 
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sswapO for Children 

New SHARED tasks don't need to copy in a new stack, nor do they need to reset the hardware ftame 
and argument pointers. Their stacks are already in place, since a new SHARED task runs in its 
parent's stack. However, the parent task needs to c^ sswapO to save its state and to copy its active 
stack to its save area. Therefore, tasksrestoreO and sswapO are called with a NEWjCHILD argument, 
and sswapO has a branch for new diildren to skip the "copy in" part 

Fudging the Parent Stack 

As mentioned above, fudge_xetnni is caUed by taskstaskO to modify the parent stack so that the 
parent does not return to aser_tasksaser_taskO. Rattier, the parent skips the user_task=iiser_taskO 
frame and returns to ttser_task=uscr_task's caller (mainO in Rgure 2-4). This routine is hi^ify 
machine- and compiler-dependent It depends on caU/retum and save/restore ctmventions of both the 
compiler and the machine. The left side of Figure 2-5 sho%vs a hypottietical example of a parent stack 
when fudge_retumO is first called. Portions of three stadc fames are showit* 

■ at the bottom is the register save area for iiser_tasksaser_taskO, containir^ the saved state of 
mainO (Le., "main's r8" refers to ttie value of hardware register r8 in mainO before 
user_taskmser_task() was called). In this exam;rie, iiser_tasksaser_laskO uses, and therefore 
saves, two registers, which on a 362 would be r as te r s r7 and t8. 

■ in the middle is the save area for taskntaskO, containing the saved state of iiser_tasksaser_task() 
or skipO, as it is labeled in the diagram and in ttie fudge retumO code. In ttiis exaii^>Ie, 
taskstaskO uses and saves four registers, r5 ttiroug^ rtt?^ 


■ at the top is the save area for fudge^xetumO, containing the saved state of taskstaskO. In this 
example, fudge^retumO uses and saves just one r^;ister, r8. 

The ellipises in the diagram re pr esent function arguments, automatics, and unused words in ttie stack 
frames. The fudge_retuxnO function must copy up the rdevant dements horn skip's stack frame to 
taskstask's stack frame, so that when taskstask's return instruction is executed, the parent will find 
itself back in mainO (in this example), with the hardware regi s ters re s tored to the vdues they had 
before skipO was called. The stack on the r^t side of Hgure 2-5 r epre sen ts the same parent stadc 
after fudge_retam has altered the stadc. The dotted arrows show where the elements from skip's save 
area have been copied. 

In the 36, VAX, and Sim-2/3 iii^ementations, fadgejretnmO ovenviites the program counter, frame 
pointer, and argument pointer (for 36 targets only) saved in taskstask's frame with ttiose saved in 
skip's frame. This causes taskstaskO to return to xnainO. 

Restoring mainO's registers is trickier. It requires knowii^ ttie layout of ttie save area for at least 
skipO and taskstaskO, and sometimes for fudge^xetumO as welL Ways of detennining the frame lay¬ 
out are discussed under "Finding Where Registers Axe Saved: AamdayoutO." Ftv now, assume 
fudge_xetumO knows how many registers are saved in each frame. 
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Figure 2-5: A 382 Stack Before and After Fudging 
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If skipO saved any registers, we must take pains to see that they are restored on taskstask's return. If, 
as is the case in the example in I^;ure 2-5, all tt»e registers saved in skip's frame are also saved in 
taskstask's frame, this is simple. We just copy the saved skipO registers over the corresponding 
taskstaskO registers, leaving any additiorud saved taskztaskO registers in place. There is room in 
taskstask's fraiire for these registers and, in the case of tiie 3B and Sun-2/3 targets, taskst a s k's 
restore instruction %vill restore all the registers we care about 

There are various difficulties with restoring the "extra" registers when skipO saves registers ffiat 
taskstaskO does not save. On sorrre targets, such as the VAX and Sun-2/3, there is no room in the 
frarrte for the additional registers; on other targets, such as the 3Bs, taskstask's restore mstruction 
won't restore any extra registers, although the save area is always large enough to hold extras. Figure 
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2<6 shows a parent stack frame where die sldpO frame contains four saved registers, Ae 

frame contains only two saved registers, and die ladge_ietani() frame contains three saved registers. 

In this example, r5 and r6 are "extra." 

Figure 2-6: Fudging When user tasksnser UskO Uses Mora Rogiatara than taricsuak 
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If fudge_Fetazn() saved any of the "extra" registers, then we can overwrite those with the correspond¬ 
ing saved skip registers. In Figure 2-6, skip!) saved i6 (main's *6), taskstaskO did not, but 
fudge_retum() also saved r6. Therefore, fudge_retum() will overwrite the r6 in its save area with the 
r6 from skip's save area. When fudge_retumO returns, r6 will be restored to the value it had when 
mamO last executed, which is what we want. Because taskstaskO did not save i6, we know that it 
will not disturb its value. 


Neither taskstaskO nor fudge_xetum(> saved the other extra register, r5, in this example. Therefore to 
ensure that when taskstaskO returns, r5 has the value it had in mainO, and not the value it had in ' 
AipO (its current v^ue), fudge_ietumO must explicitly set the hardware register r5 to the value saved 
in skip s frame (main's i5). This is safe to (k), because none of the intervenmg functions use i5. The 
function fudge_retumO calls an assembly language function to overwrite r5 (or any ottier extra regis¬ 
ters). After fadge_retum() and taskstaskO return, all the registers will have the values they had when 
mainO last executed on the parmu stadc. ’ 


There IS one 6nal step: arranging for the slack pointer to be in the right place after taskrtask returns 

This depends on the way the target executes a return. Without some adjustment, the stack pointer wiu 
be set one frame too high (at the top of skip's friune instead of at the top of main's frame). 

On the VAX, a return insteuction restores the frame and argument pointers from those saved in the 
stack, pops the saved registers off the stack, and adds the number of arguments diat are on die 
(as given in the argument descriptor, see Figure 2-1) to die stack pointer. We can cause the «m/.i, 
pointer to be restored correcdy by a#isting the argument descriptor in taskstask's frame to indude all 
the words m the skip frame in addition to the arguments. In other words, fudge retumO alters 
taskstask's frame to look as diough there is a big argument list 


On theSBs, a return iristruction restores the frame and argument pointers from those saved on the 
stack, but the stack pointer is given die value of die argument pointer of the returning function. This 
presents a problem for a fudged parent stack: when we return from taskstaskO, the frame and argu¬ 
ment pointers are reset to point to main's frame; as we wanted, but the new stack pointer points 
where taskstask's argument points was, which is higher dian needed and wastes space.^' What we 
want is to have the stack pointer point to where sIot's argument pointer was. We arrange for diis 
wth an assembly langiMge function, FUDGE_SPO,^ which is defined fc)r the 3Bs to take an argument, 
the sk^iO argument pointer, and to reset the current argument pointer (taskstask's) to die argument 
FUDGE_SPO is called just before taskstaskO returns on the parent side. Once FUDGE SPO is raiUH 
no arguments to taskstaskO can be referenced. The taskstaskO constructor returns the ttiis pointer 
which IS Its in^lidt first argument Tfre this argument is usuaUy in a register, but if it is not 

taskstask wiU need to reference it through the now-dianged argument pointer when it sets the return 
value. Therefore, FUDGE_SPO also copies the value of taskstask's first argument to be 
aser_tasksuser_task's first argument to ensure that taskstask's return value wUl be set properly. 


The Sun-2/3 targets have a similar problem to that described above for the 3B targets. The solution, 
towevCT, is different. The Sun-2/3 compiler typically generates a function return sequence of diree 
instructions: movem, unlk, and rts. The movem instruction restores the registers denoted by a 
and uses an offset from die frame pointer to find the register save area. The wniy instruction resets 
the frame pointer to be the one saved in the stack, and also resets the stack pointer to point at the 
saved return program counter on die stack. Rnally, the rts instruction pops the program counter off 
the stadc, leaving the stack pointer pointing at the top of die frame of the function that ftg 
returning functioru As with the 3B targets, after a parent task (whose stack has been fudged) returns 
from taslcitaskO to mainO (in the example), the stack pointer points to the top of the skipped frame. 


2-48 


Library Manual 





A Porting Guide for the Cm> Coroutine Library 


We compensate for this with a variation in FUDGE_SP() and fudge tetmnO dte Sun>2/3 targets.^ 
Instead of overwriting taskntask's return pc widi sidp's return pc, fodge_zetuniO overwrites 
taskztask's return pc with the address of an assembly language function, fudge_sp(). When the patent 
task returns through taskstaskO, it calls FLJDGE_SPO, «^ch sets a global variable, Skip_pc_p, to 
point to skip's return pc in the stack. Then tasl^taskO retuins to fadge_spO,^ which sets Ae stack 
pointer to Skipjpc_p, and executes an rts instruction, which pops sk^'s~saved return pc off rite stack, 
leaving the stack pointer at the top of mainO's frame. 

Finding whara registers are saved: FiameLayoutO 

As mentioned above, fudging tte parent stack lequiies knowing the laycnit of die stack frames sur> 
roxmding the one to be fudged. This is not a pnMem fcu’ targets with sdf-describing stack frames, 
such as the VAX Targets that do not have sdf-describing stack frames, such as the 3B and Sun-2/3, 
include a structure, defined in the source file fodge^c; calM ErameL^rouL FrameLrqroat has different 
members, dependii^ on the target. It always has a constructor, whidi initializes the members so diat 
fadge_retnm() has the information it needs to modify die parent stack. 

FiameLayout for the 3B Processors 

On the 362 and 3620 targets the layout of saved registers follows horn the number of registers saved 
by the function. On both targets, the size of the save area is invariant; if fewer than all die roisters 
are saved, some slots in die save area will be unused and contain garbage values. The number of 
registers saved is found looking at the save instruction of the function in cpiestion. By convention, 
the save instruction is die first instruction of die function. Hie easiest way to find die save instrucdcm 
for a given function,/, is by dereferendr^ a pointer to the hincdcm. However, when/is a constructor, 
as both taskstaskO and user_tasksuser_taskO are^ one cannot take its address. In diis case, one can 
find die save instruction for/by using^ pointer to die return pc saved in thefs frame; backing up 
one instruction to find the instruction to c^/, and followir^ the destination argument of the call to 
find die save instruction. 

On the 36 targets, FrameL^out contains one demenfc njnved, nriiich r ep r esen ts die number of rois¬ 
ters saved in the frame. The FrameL^raut constructor finds a_saved for the frame denoted by its 
frame pointer argument FrameLr^outsFcameLayoulO uses die frame pointer to find the return pc, 
which points to the instruction after the call to die denoted functiort fr backs one instruction to get 
a pointer to the call instruction,^ then decodes the call instruction (usir^ a function called 
call_dst_ptrO) to get a pointer to die function denoted by the frame pointer argument Rnally, it 
dec^es the save instruction (pointed to by the function pointer) to find die nuniber of roisters saved 
in the frame. 

FiameLayout for the Sun-2/3 Target 

On die Sun-2/3 target FrameL^ut contains two dements: o^Mt die c^et of die top of die roister 
save area from the frame pointer, and mask, the bit mask denoting which roisters ivere saved. The 
FrameL^oat constructor for the Sun-2/3 initializes the structure by a method gmitar to that described 
above for the 36 targets, whidi involves fdlowing the return pc to find the call, and decodir^ die call 
to find the destination of the calL Hnally, it decodes die instructicms in die function prologue (which 
can vary), to find die mask and die o^et 
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A Porting Guide for the Cm- Coroutine Library 


Source File Organization 


The target-dependent parts of the task library axe isolated in four source files: 

hw_stadcii 

~ contains target-dependent macro, const, structure, aiul fuitction dedarations for each sup¬ 

ported taxget (sunouirded by #ifilefo). 

hw stack.c contains definitioirs of taiget-deperwient functions for each supported target (surtourKied 
#ifde£s). Many of these axe short assemUy language hmctions which set or return 
hardware legistets. 

fudges There is a version of fodgc^c for each suprorted target cuirerrtly: fa<^ex3b, 
fuc^e.cvax, fadgex386, artd fudgex,68kr These files contain definitions of 
tasksfadge_TetiixnO and ficameLaToatsFxameLjTontO (for the targets foat need it). 

swap.s There is a ver»on of swap^ for each s u pported target curreirtly: swapa3b, sws^.s.vax, 
swap.s386, and sw3^.s.68k. These files contain foe assemUy language functions swa^O 
and sswapO. 


Hints for Porting the Task Library to Other Processors 

■ Draw pictures (like those in Hgure 2-1) of foe stadc frame layout for foe target to whidi you are 
porting. Detailed pictures of foe register save areas of several frames on foe stadc, like foose in 
Rgures 2-5 ar»d 2-6, are helpful in writir^ fadge_retui!nO. 

■ Becotire familiar wifo the sequettce of operations in function calls and returns. Write and com¬ 
pile some sample C or C-m- programs and look at foe generate d code to see what kinds of call 
axul return sequences the com{nler gerterates, in what order registers are used, and so forth. A 
fast way to write the cop^ in and copy out loops for sswrqrO is to write them in C aanpfle foem 
with the -S option, and transcribe foe genera te d code into sswapO. 

■ The implementation of the task library was designed to be both maintamable and, as far as pos¬ 
sible, portable across both madiines and compnlers. These goals are sometimes mutually 
exdusive, and in foose cases, we aimed for maintainability and portabQity aaoss diHerent coiit- 
pilers for the same machirte (where possible). Some porters may %vant to write some of the 
assembly language funcdoits in hw_stadcc as macros that depotd on positional parameters and 
compiler conventions. For example, FPO returns the frame pointer for the calling function. This 
could also be written for foe 3B targets as a macro foat takes as an argument foe first automatic 
variable of the function arui returns foe address of that variable, or for the VAX takes foe saxrte 
argument and returns foe address of foat variable minus oite. This only works if foe macro is 
given the first autoitratic as an argument, if foe compiler assigns automatics in foe order in 
which foey are dedared, and if foe optiinizer leaves the automatic on the stack, even if it is 
never read nor written. 


2-50 


Library Manual 





Footnotes 


1. ^ ori^ veraon of this pap^ was written in 1980 by B. Stroustrup and revised in 1982 by 
him. Since then both the task library and C++ (then known as "C with Classes") have rKancwi 

substantiaDy, but the interface to the task library has been left intact This has allowed Sdw^ 

pms to run wi A new versions of the libiaiy, but has prevented any updating of the style of 
the interface, which does not conform to current ^ 


levised 1^ J. E. Shopiio to leBect the present state of affturs. 
I haye added a few notes (in sans-serif type) where changes have been significant and have 
made numerous syntactic chai^, etc, wifttout further comment 


2 . Many of^inember functions are inline, but their definitions are not shown here to prevent 

clutter. C3ass task is derived from class scfaed which is derived ftom class object oLs object 

IS a s^te base class used ly most classes in the task system. It contains some of the pointeis 

used by ttie task system s internal '^house-keeping/' Class object is described under 'Tlie 
object Gass." 


3. "nie class may have other ineinber functions, of course, which inay be called by the constructor 

or by any other function accordmg to file usual rules of C++. 

4. When the first task is created, mainO automatically a task itH f 

5. It is a fairly simple job to add a new kind of task that letums some other datatype. 

6. The handling of run time errors will be described M ow 

7. Thus qheadspendingO returns 1 if the queue is empty and 0 otherwise. Correspondingly. 
qtailspendingO returns 1 if the queue is full and 0 ottietwise. 

8. The default maximum size for a queue is 10000. That is; the queue can hold up to 10000 
pointeis to ol^ects. It does not, however, pre-^allocate 

9. The original task package had a number of giobai variables, including tfaistask. task and 
clock. They are now all macros which expand to mBne functions that return the valuM of private 
static variables. Thus programs that just read the values wil be unaffected, but programs that try 
to set them (which was always illegaO will fail to compile. 


10. Waitlistt) is an example of a function whose form does not satisfy current esthetic standards. 

11 . In a quasi-paraUel^tem this wffl only be true provided no infinite loop without task wstem 

calls exists. Sudi a loop constitutes an error fiiat only a system witti true paraOdism or tiine 
slicing can recover from. 

12. Coroutines can exchange control among themselves ntore fteely than ordinary functions and 

procedures. In the usual function calling discipline, when one procedure (more precisely, one 

instance of a prxedure) executes a procedure caU, a new instance of file procedure is 
created, and the calling procedure waits until the called procedure (and any procedures it may 
call) returns. A procedure instance is initiated v/hen the prooedure is and is destroyed 
when it returns. When one coroutine (coroutine instance) initiates another it not wait for 
the new coroutine to end, but instead it can be resumed ufiiile file new coroutine is stiU active. 
A running coroutine can rdinquish control to any waiting coroutine without its 

state and later regain control and continue fixmi where it left off. 

13. Oass object is fiie base class of most cl ass es in the task system. We use the typewriter font 
for programming language constructs. 
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14. Semaphores which are used for mutual exclusion are initialized with one excess signal so that 
the first lock call will succeed. 


15. But watch out for deadlock. 

16. To the extent that the target hardware dictates subroutine linkage and stack frame laj^ut, tlw 

compUer is less important. Some machines, like the 3Bs and the sup^rt a ^a^stack 
frame* the task library is largely independent of the compiler on these machines. The 68000, 

not^pportTs^edficSck frame anangpment; the task library on ^m^e 
also depends on the compiler conventions for the stadc frame. TRie word target ^ be used in 
this paper to denote an instance of either a processor or a compiler/processor platform. 

17. The stack frame layout on the AT&T 6386 WGS is similar to that on the Sun-2/3 Workstations. 
The library port is also similar on these targets. 

18 See "A Set of C++ for Co-routine Style Programming" or "Extending foe C-*^ Ta^ S^ 

tern for Real-Time Control" for details. The ways in which a task is put to sleep and awakened 
are target-independent 

19. This is true for our example targets. Some targets may use a caller save convention rather than 
a callee save convention. 

20 It may not be immediately obvious that aH registers must be saved on a task switch. Oi^der a 
task A, which has a function / that uses all the registers. It calls another function, g, which ^ 
less than all the registers, say two, and foerefcwe only saves two registers m its save ma. ^ 
task switch occurs before g returns, and task B uses all foe registers, it will destroy those needed 

by task A's function /. 

21. It can happen foat a SHARED tadc will resume execution without having ever been di^laced by 
another task sharing the same stack. 

22. For example, DEDICATED tasks do not work with 3B2s runnir^ versions of the UNIX system 
earlier than SVR3. 

23. The function resumeO is virtual, with definitions for tasks and timers. Only tasks are relevant 

here. 


24. If foe suspending task is TERMINATED, then swapO does not save its state. 

25. Writing the code for stack copying of SHARED tasks in assembly language ad^ mote rort^lex- 
ity than we would like to the job of porting the task library. It would be possible to^ a C 
function to copy out foe susp^ed task's stadc to its save area. Howevw, copying the resurri- 
ine task's stadc back in presents a problem: If foe resuming task's stack is taller than foe stock 
on whidi we are executing, a cofty-in will overwrite the current slack frame. 

tion is careful to move aU the data it needs from foe frame into r^;isters, so that if ^ harne is 
overwritten, sswapO can still complete successfully. But if sswapO called a C function to do foe 
copy-in, that function might overwrite its own stack frame, making it impossible to return to 
sswapO to finish the task switch. So lor^ as the cc^4n must be %vritten as part of sswapO, it 
seems little more trouble to write the complementary copy-out in assembly language as weU. 

26. When foe prevOnStodc task and foe resuming task are the same, restoreO calls sw^O, rafoer 
than sswapO, to do the task switch, as no stadc copying is necessary. 

27. The constructor toskstoskO only acquires stadc space for DEDICATED tasks, that is, tasks foat 
have their own stock. SHARED tasks wfll need space in which to save foe current (or parent) 
task's active stock; sswapO takes care of that, as described above. 
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28. Only one child is activated at a time — remember, no pre-emption — and the child runs 
immediately, so it is safe to put these registers in a global, and more spaoe-effident than keeping 
them as part of the task obj^ 

29. Note that, in Figure 2-5, the saved i5 and r6 in taskstask's frame are labded "main's iS" and 

main's i6" radier than "skip's r5" and "slap's r6." This is because in this example, skipO does 
not use r5 or r6; mainO was the last function to use r5 and i6. Therefore, foe values of i5 and r6 
saved in taslcfoisk's frame are the values that i5 and had when mainO was running. 

30. The restore instruction for foe VAX doesn't qiedfy vfoich registers to restore. 

31. In the case of a task that repeatedly spawned duldren, the stack pointer would grow unneces¬ 
sarily, eventually causing the stack to overflow. Each time foe parent task returned horn 
taskrtask, foe stack pointer would be an additional flame higlier than needed, and a new call to 
taskstask would start buildup the next flame ndiere tfie stadc pointer pointed. 

32. FUDGE_SP() is defined as a do-ttothii^ macro for foe VAX 

33. The AT&T 6386 WGS port of the task library also uses fois technique. 

34. When taskstaskO returns, the hardware registers are re s to r e d to the values they had in 
and the flame pointer is set to flte value it had in mainO, but foe program counter is set to 
fudge_spO. 

35. Some of these flames are for user functions, so we caimot rdy on techniques whidi require the 
C-M- code for the function to be written so as to generate code fliat creates flames wifo some 
particular layout. 

36. Because 3B instructions can be of various sizes, one caniwt deterministically "back up" one 
instruction. FrameLayoutsFrameLayoutO subbacts each possible instruction size flom the 
return pc and decodes foe resulting pointer to dieck for a call opcode and legal operaruls. 

There is a small possibility, reduced by flunfliarity wifo the conqnler, flrat these heuristic 
mefoods could yield more than one candidate call instruction. 

37. The .68k suffix used for the Sun-2/3 target is something of a misitomer. These files were written 
specifically for Sun compiler/68K platforms; foey will not necessarily work on all 68K {fiatforms, 
for example, the AT&T compUer for fite 68X Ffowever, foe fifdefs in foe source say iifdef 
mc68000. 
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NOTE 


This chapter is taken drectiy from a paper by Jerry Schwarz. 


Abstract 


The iostream libraiy sup^xMls formatted I/O in C-m-. This document, containing many exan^es, is an 
introduction to the library. Overloading arid other C++ features are used to provide an interfece ftat 
combines fiexibUi^ and type cheddng. Predefined and user de6ned operations are easily mixed. The 
streambuf class supports alternate sources and sinks of diaracters. 

The manual pages for the iostream libraiy can be found in Appendix A. 


Introduction 


C aiui C++ share foe property that they do not contain any ^ledal input or outyut «e«arpm^^ 

Instead, I/O is implemented using ordinary tnedianisms and standard libraries, fo C fois is foe ytd fo 
libraiy. In C++ (as of idease 2J) of foe AT&T C++ Language ^rstem) it is foe iostream libiaiy. 
Because C++ is an extension of C it is possible for a C++ program to use Usii^ stdio may be 
the easiest way for a C programmer to get started wifo C++, but uang is not a good style for 
C++ I/O. Its main drawbacks are its type insecurity and foe inability to extend it oonsistendy for user 
defined classes. 

This document consists mainly of examples of foe use of parts of foe iostream libraiy. It assumes a 
reasonable familiarity with C++, indud^ such extensions to C as refereitoes, operator overloadii^ 
and the like. An attempt has been made to create exam;^ that not only iDustrate features of foe ios¬ 
tream library, but r e present good programming stj^. A programmer who is new to C++ may copy 
the examples "cotricbook styde," but cannot be said to have masfered C++ until he or she understands 
the examples. 

Some of the examj^ are moderatdy con^dicated and demonstrate advanced features of foe iostream 
library. These are included so that foe document will continue to be useful as an aid even after the 
programmer has written a few programs using iostreams. The aufoor is annoyed by "tutorials" foat 
show how to do simple foii^ foat he could figure out himsdf, but are silent about foe harder, more 
sophisticated kinds of code foat he frequently wants to write. 

This document is not a conq>lele description of the iostream library. Some cfesses and membeis are 
not described at alL Some arc used wifoout complete descriptions. The reader is r e fe rred to foe ios¬ 
tream man pages for more details. 

The dedarations for foe iostream library exist in several header files. To use aity part of it, a program 
should include iostreamii. Other header files may be needed for ofiter operations. These are men¬ 
tioned below, but foe #include lines are never put in the exaiiqiles. 
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The iostream libraiy is divided into two levels. The low levd (based on the streambuf class) is 
responsible for producing and consuming characters. This level is an independent abstraction and 
may be used without the upper level. This is appropriate when the program is moving characters 
around without much (or any) formatting operations. 

The upper level is re^nsible for formatting. There are three significant classes, istream aiui ostream 
are re^x>i\sible for input and output formattmg, respectivdy. They are both derived from class ios, 
which contains members relating to error coTtditions and foe interface to the low level. A fond class, 
iostream, is derived (multiple inheritance) from bofo istieam aitd ostream. It plays only a minor role 
in the library. A "stream dass" is any dass derived from istream or ostream. 

The topics covered in this document are: 

■ Output — predefmed output conversiorts, ways to deal with errors, and ways to adapt the 
library for output of user classes. 

■ Input — predefmed input conversions, and ways to adapt foe litnary for input of user classes. 

■ Corkstructing spedalized streams — file I/O, and incore operations. 

■ Format Control — An ios contains sonte format state variables. This section describes how they 
are manipulated by user code and interpreted by foe {nedefirted operations 

■ Manipulators — A powerful method for customizing operatiotts 

■ streambufs — How to use the low levd interfoce. 

■ Deriving Streambuf Cia«P«i _ Methods for creating ^redalized classes that specialize streambuf 
to deal wifo alternate producers and coiuumers of characters. 

■ Extending Streams — Derivir^ classes from istream and ostream, addii^ state variables, and ini¬ 
tialization issues. 

■ Comparison of I/O libraries. 

■ Compatibility — Converting a program foat uses foe old stream library to use foe new library. 


Output 

Suppose we want to print the variable x. The ntain nrechanism for doing output in the iostream 
library is the insertion operator «. This operattx’ is usually called left $1^ (b^use that is its built-in 
meaning for integers) but in the context of iostreams it is called insertiott. 

cout « X ; 

coat is a predefined ostream and if x has a numeric type (other than diar or unsigned char) the inser¬ 
tion operator wOl convert x to a sequence of digits and purrctuation, and serul this sequence to stan¬ 
dard output There are different operatiotts depending on foe type of x, and foe mechanism used to 
select the operator is ordinary overload resolution. The irtsettion operator for type t is called foe "t 
inserter." 

If we have two values we might do: 
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cout « X « y ; 

which wUI output x and y, but without any separation between ti»em. To annotate the output we 
might do: ^ 

oout « "x«" « X 
« ",y*" « y 

« ■,sun»“" « (x + y) « "Vn* ; 

This will not only print die values of x, y, and dieir sum, but labds as wdL tt uses the string (diar*) 
iitserter, which copies zero terminated strings to an ostream. 

Notice the parend»eses around the sum. ‘Htese are not needed because die precedence of f-is hi^ 
than that of«. But, whm using « as insertion, it is ea^ to forget that C++ is giving it a precedence 
appropriate to shift Gettiiig in the habit of aiwa 3 rs putting in parentheses is a good way to avoid 
nasty surprises sudi as having cont«x^ output x radier than x&y. 

The output might look like: 

3^23, y»lS9, sunwl82 


A pointer (void*) inserter is also defined. 

int X - 99 ; 
cout « ax ; 

It prints die pointer in hex. 

A char inserter is defined: 

char a - 'a' ; 
cout « a « '\n' ; 

This prints a and newline. 

User Defined Insertion Operators 

What if we want to insert a value of type? 

Inserters can be declared for classes and values of class type and used ividi exacdy die same tyntax as 
inserters for the primitive types. Hiat is^ assuming die proper declarations and definitions, the exam¬ 
ples from the previous section can be used when x or y are vaiiaUes widi types. 

The simplest kinds of examples are provided by a struct that crmiaifK a few values. 

struct Pair { int x ; int y ; > ; 

We want to insert such values into an ostream, so we define: 
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ostreamfi operator« (ostEeani& o. Pair p) ( 
return o « p.x « " " « p.y ; 

} 

This operator inserts two integral values (separated by a space) contained in p into o, and then returns 
a reference to o. 

The pattern of taking an ostreamac as its first argument and returning the same ostream is what makes 
it possible for insertions to be strung together conveniently. 

As a slig^idy more daborate examfrie, consider the foIlo%vii^ dass, which is assumed to implement a 
variable size vector 

class Vec ( 
private: 

public: 

VecO ; 
int size () ; 
void resize(int) ; 
floats <^zator(] (int) ; 


1 ; 

We imagine that Vec has a current size, which may be modified by resize, and that access to indivi¬ 
dual (float) elements of the vector is supplied by Ae subscript operator. We want to insert Vec values 
into an ostzeam, so we declare: 

ostreans operator« (ostreans o, const Vecs v) ; 

The definition of tiiis operator is given below. Using Vecfc radter dtan Vec as the type of the second 
argument avoids some unnecessary copying, which in this case mig^it be expensive. Of course, using 
Vec* would have a similar advantage in terms of performance, but would obscure the fact that it is the 
value of the Vec itself that is being output, aiKl not the pointer. 

The definition mi^t be: 

ostreanfi ^eratoz« (ostreamfi o, const Vecc v) 

( 

o « •(" ; // prefix 

for ( int X - 0 ; X < v.sizef) ; ++x ) 

// use oonina as separator 
if { x!-0 ) o « ; 

o « vixl ; 

> 

return o « "]" ;// suffix 
1 

This will output the list as a comma separated list of numbers surrouitded by brackets. The code takes 
care to get the empty list ri^t and to avoid a trailing comma. 
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Propagating Errors 

None of examfrfes so far has checked for errors. Omitting such checks would be bad s^k, except 
that the iostream library is arrar^ed so that errors are propagated. 

Streams have an error state. When an error occurs bits are set in the state acomling to the general 
category of the error. By convention, inserters ignore attempts to insert thii^ into an ^^ith 

error bits xt, and such attempts do not diai^ the stream's state. The error bits are declared in an 
enum, which is declared inside tiie dedaration of jos. 

class ios { 

enum iojstate ( 9oodbit-0, eofblt*!, £aLiIbit«2, badbit«4 > ; 

1 ; 

ios:%oodbit is iK>t really a "bit" It is zero aitd indicates die absence of ai^ bit 

In the definitions of the Pair artd Vec inserters, if an error occurs some wasted conputation may be 
done as the code does insertions that have no efiect But eventually the error will be prtmeriy pro¬ 
pagated to the caller. 

It is a good idea to chedc the output stream in some central place. For 

if (loout) error ("aborting because of output error") ; 

The state of cout is examined with operator!, which will have a rum-zero value if die state an 

error has occurred. This and other examples in this document assume diat enotO is a function to be 
called when an error is discovered, and that it does not return. But etzorO is not part of die iostream 
library. 

An ostream can also appear in a "boolean" position and be tested. 

if ( cout « X ) return ; 

: // error handling 

The magic here is that ios contains a definition for operator void* that returns a iK>n-null value when 
the error state is non-zero. 

An explicit member function also exists: 

if ( ... , oout.goodO ) return ; 

... : // error handling 

The reader is referred to the man pages for odier member functions diat examine die error state. 

Flushing 

In many circumstances die iostream library accumulates characters so diat it can send them to the ulti¬ 
mate output consumer in largo- (presumably mote efficient) chunks. This is a problem mainly in 
interactive programs where the user may need to see the output before entering input It can also be a 
problem during debugging when the programmer may need to see how far die program has gotten 
before dumpi^ core. The easiest way to make sure that everydiing inserted into an ostream has been 
sent to the ultimate consumer is to insert a special value, flush. For example: 
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cout « "Please enter date:" « flush ; 

Inserting flush into an ostream forces all characters that have been previously inserted to be sent to the 
ultimate consumer of the ostream. flush is an example of a kind of object known as a manipiiia^^- a 
value that may be inserted into an ostream to have some effect It is really a function that takes an 
ostieam& argument and returns its argunnent after performing some actions on it 

Another useful way to cause fludui^ is the endl manipulator, which inserts a newline and then 
flushes. 


cout « « z « endl ; 


Binary Output 

Sometimes a program needs to output Initary data or a single character. 

int c-'A' ; 
cout .put (c) ; 
cout « (ctmrlc ; 

The last two lines are equivalent Eadi inserts a nitgle duuacteifA) into cout 

If we want to ouqnit a larger direct in its Irinary form a loop using put would be possible, but a more 
effldent method is to use the write member. For example: 

cout.write ((char*)«z, sizeof(z)) 

will output the raw binary form of x. 

The reader should notice that the above example violates C++ Qrpe discipline by converting &x to 
diar*. Sontetimes this is harmless, but if the type of x is a class with virtual member functions, or one 
that requires nort-trivial constructor actioits, the value written by the above cannot be read back in 
properiy. 


input 


Iostream input is similar to output It uses extraction (») operatme fluit can be struitg together. For 
example: 

cin » z » y ; 

inputs two values from the ptedefmed istream dn, which is 1^ default flie standard hqmt The extrac¬ 
tor used will be appropriate for die types. The lexical details of numbers are diyiKsaed below under 
"Tbrmat ControL" Whiteq>ace characters (spaces, newlines, tabs^ form-feeds) will be ignored before x 
and between x and y. For most types (including all Are numeric ones), at least orte wdiite^ce charac¬ 
ter is recjuired between x and y to mark where x ends. 

There is a dur extractor. For example: 
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char c ; 
cin » c ; 

skips white^>ace, extracts ttie next visible character from dte istream and stor es it in c ("Non- 
whitespace" is too u^y a phrase for extensive use. This document uses "visible" instead. Strictly 
speaking this tenniiK>logy is incorrect For exarrq^, it classifies oorttrol diaiacters as visiUe. But the 
term is reasottably euphonious and reasonably d^.) 

Sometimes it is desirable to extract the next character uiKortditionally. For exair^ile: 

char c ; 
cin.get(c) ; 

The next character is extracted and stored in c, whether or not it is white^Moe. 

User Defined Extraction Operators 

Creating extractors for classes is similar to creating inserters. The Pair extractor could be tous: 

istreanfi operator»(istreaii>fi i, PclLtS pair) 

{ 

return i » pair.x » pair.y ; 

) 

By convention, an extractor converts draracters from its first (istreamde) argument, stores toe result in 
its secortd (refdertoe) argument, and returns its first argument Maldng toe second argument a refer- 
eiKe is essential because toe purpose of an extractor is to store a rtew value in toe second argument 

A subtle point is the {xopagation of errors by extractors. By convention, an extractor Whose first argu- 
ment has a noivzero error state will not extract any more diaracters firom toe istzeam and wfll not 
dear bits in the error state, but it is allowed to set previously unset e rro r Nts. Furtoer, an e x trac tor 
that fails for some reason must set at least one errm’ bit The code in toe Pair e x trac to r does rurthing 
explidtiy to respect these conventions, but because the only way it rrtodifies i is wito extractors toat 
honor the conventiorrs, toe conventions will be respected. 

Conventions also apply to toe meaning of toe irKiividual erm’ bits. In partkular iossfailbit indicates 
that some proUem was encountered vvhile gettir^ diaracters from the ultimate producer, while 
iossbadbit means that the characters read from toe stream did not conform to toe expectation of the 
extractor. For example, suppose that toe components of a Pair are suf^iosed to be non-zero. The 
above definition might become: 

istceamfi opezatoc»(istzeainfi 1, Pairs pair) 

{ 

i » pair.x » pair.y ; 

if ( !i ) return i ; 

if ( pair.x — Oil pair.y — 0 ) ( 

i.clear(ios: :badbit|i->rdstate()} ; 

1 

return i ; 

1 

This uses the (misleadingly ruuned) dead) member function to set the error state to indicate toat the 
extractor found incorrect data. Oring iossbadbit with i->fdstate() (toe current state) preserves any bits 
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that may previously have been set. 

The Pair extractor has been defined so that it can input values that were output fire Pair inserter. 
Maintaining this symmetry is an important gerreral principle that is w(»th some efiort 

The next example is fire Vec extractor, which will require an <^>etung I foDowed by a seqtietrce of 
nuinbers,foUowedbyaJ. Recall that the Vec inserter uses, as a separator and does not insert any 
white^ce between numbers. The extractor must accept sudi input It will accept slightly more 
general formats. In particular it allows extra white^race, and it allows any visiUe characteto be used 
as a separator. It also deals properly with a variety of special conditions such as errors in the input 
format ^ 


istzeanfi apecatoc»(lostxeain& i, Veca ▼) 

{ 

int n • 0 ; // nuBbet of elesients 

diar delin ; 

V. resize (n) ; 

// verify opening prefix 

i » delira ; 

if ( deliin ) ; 

i.putbadc (delirn); 

i.cleardos: :badbit|l.rdstateO) ; 
return i ; 

1 

if ( i.flags!) a los::s)cipws ) i » ns ; 
if ( i.peekO '1' ) return i ; 

// loop 

while ( i aa delist ) ( 

V. resize (++n) ; 
i » vlrr-l] » delist ; 

) 

return i ; 

1 

The steps this code performs are: 

■ Turn V into an enq)^ vector. This is done by fire first resize operation. 

■ Verify that the next diaiacter in the istream is [. 

If file next diaracter is rtot [ (or if fite state of the fostieam already has mor bits set), maih the 
state of i as bad, put delim back in e (where it may later be extracted again), and rehim. Put¬ 
ting deliffl bade in the stream is not essential but it is consistent wifii fiie behavior of the 
predefined extractors. 

■ Optiorrally skip some whitespace. 

Whether to skip is controlled by the iossskipws fl^ set in a orilection of Wts known as i's for¬ 
mat flags. This bit also controls skipping of whitespace in the predefmed extractors. If it is set, 
white^)ace was skipped bdore extracting the character stored into 
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a If the next character is L the ii^ut represents an empty vector and since v has already been 
resized the extractor can just return. 

The next character is examined using the peekO member function. This returns the next charac¬ 
ter that would be extracted but leaves it in the stream. 

■ The code now loops, extracting numbers aixl ddimiters until either ttte dosiitg 1 is found or an 
input error occurs. An exf^t check of the state of i is required to prevent an infinite loop 
should an error occur in extracting vec[n>l] or delim. 


char* Extractor 

A useful extractor, but one that must be used %vith cautiot), takes a diaz* second argument For exam¬ 
ple. 


char p[100] ; cin » p ; 

skips white^)ace on dn, extracts visible diaracters firom dn and copies tiiem into p until another vdti- 
te^ce character is encountered. Hnally it stores a terminatiz^ null (0) character. The diar* 
must be used with caution because if there are too nrany visiUe characters in die istream, die array 
will overflow. 

The above example is more carefully written as: 

char pllOO] ; 
cin.width(sizeo£(p)) ; 
cin » p ; 


There are very few circumstances (periiaps there are none at all) in whidi it is appropriate to use Ihe 
char* extractor without setting die "widto" of the istream. 

To make ^ledfying a width more convenient, the setw manipulator (declared in iomanipJi) may be 
used. The above example is equivalent to: 

char p[100] ; 

cin » setw(sizeo£(p)) » p ; 


Binary Input 

The char extractor skips whitespace. Programs fiequendy need to read the next character whether or 
not it is whitespace. This can be done with the getO member function. Forexanq4e, 

char c ; cin.get (c) ; 
getO returns the istream and a common idiom is: 
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char c ; 

while ( cin.get(c) ) ( 
} 


Programs also occasionally need to read binary values (eg., those written with writeO) and diis can be 
done with toe readO member function. 

cin.read((char*) «x,sizeof(x)) ; 

This does the inverse of the earlier write example (namely, it inputs toe raw binary form of x). 

If a program is doing a lot of character binary input, it may be more efficient to use toe lower level 
part of toe iostream library (streambuf classes) directly rather than throu^ streams. 


Creating Streams 


The examples so far have used toe predefined streams, cin and cout Fot some programs, reading 
from standard input and writing to standard output suffices. But other programs need to create 
streams with alternate sources and sirdcs for characters. This section dwruwjfs the various kmds of 
streams that are available in toe iostream library. 

Files 

The classes ofstream and ifstream are derived from ostream and istream and inherit the insertion and 
extraction operations respectively. In addition they contain members and constructors that deal with 
files. The exarrqjles in tois section assume that the header file fstreamJi has been 

If the program wants to read or write a particular file it can do so by declarii« an itetream or ofs¬ 
tream respectively. For example, 

if stream source ("from") ; 

if ( ! source ) error ("unable to open 'from' for ii^ut"); 
ofstream target ("to") ; 

if ( Itarget ) error("unable to open 'to' for output") ; 
char c ; 

while ( target sc source.get(c) ) target.put(c) ; 

copies toe file from to toe file to. If the ifstreamO or ofstzeamO constructor is unable to open a file in 
toe requested mode it indicates this in toe error state of toe stream. 

In some circumstances a program may wish to declare a file stream mthout spedfyii^ a file. This 
may be done and toe filertame suj^lied later. For examine: 

ifstream file ; 

• • • # 

file.open(argv[l]) ; 
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It is even possible to reuse the same variable by dosing it between calls to openO. For exaii^}le: 
ifstreain infile ; 

for ( char** f - Caxgvtl] ; *f ; ++f ) { 
infile.open(*f) ; 

• • • # 

infile.closed ; 

1 


In some drcumstances the program may already have a file descriptor (sudi as the integer 0 for stan¬ 
dard input) and want to use a file stream. For exan^e, 

ifstream infile ; 

if ( strcapIargvUl,*-*) ) infile.open(argvUl,input) ; 
else infile.attach(0) ; 

opens infile to read a file named by aigvll], unless the name is In foat it tvill connect 
with the standard input (file descriptor 0). A subfie point is fiiat closing a file stream (eidier e)q>lidtly 
or implidtly in foe destructor) will close foe underlying file descrq>ttn’ if it was opened «vifo a 
filename, but not if it was supi^ied wifo attadi. 

Sometimes the program wants to modify foe way in which foe file is opened or used. For example, in 
some cases it is desirable that writes append to the end of a file rafoer than rewiitit^ foe previous 
values. The file stream constructors tate a second argument foat allows such variations to be 
specified. Forexan^e, 

ofstceam oucfile(*oue*,xos: :apptios: :nocceate) ; 

declares outfile and attempts to attach it to a fite rtanwd out Because iosc^p is specified all writes 
will append to the file. Brause iossnocreate is specified the file will not be created. That is, foe open 
will fail (indicated in outfile's error status) if the file does not previously east The enum open_mode 
is declared in ios. 

class ios ( 

enian openjnode { in, out, app, ate, nocceate, mc^laoe ) ; 

); 

These modes are each individual bits and may be or'ed together. Their detailed meanings are 
described in the man pages. 

Sometimes it is desirable to use the same file for both input and output fotream is an iostxeam (a 
class derived via multifde inheritance from both istzeam and ostream). The fype strean^os is for 
positions in an iostream. For exart^le. 
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fstream tnp("tinp*,ios: rinlios: :out) ; 

streanpos p >■ tnp.tellpO ;// tellpO returns current position 
tnp « X ; 

tnp.seelcglp) ; // seelcgO repositions iostream 

tap » X ; 

saves the position of the file in p, writes x to it, and later returns to the same position to restore the 
value of X. 

A variant of seekgO takes a streamoff (integral value) and a seek dir to specify relative positionine. 
For example, ~ r- 

tap.see)cg(-10,ios: :end) ; 

positions the file 10 bytes from the end, and 

tap.seekg(10,ios: :cur) ; 

moves the hie forward 10 bytes. 

Incore Formatting 

Despite its name, the iostream library may be used in situations that do not involve input or output 
In particular, it can be used for "incore formatting" operations in arrays of diaracters. These opera¬ 
tions are supported by the classes istrstream and ostrstream, wdiidi are derived from and 

ostream respectively. The examples of this section assume that the header file strstreanuh has been 
included. 

For example, to interpret the contents of the string argvll] as an integer value, the code might look 
like: 


int i ; 

lstrstrean(argv[l]) » i ; 

The argument of the istrstreamO constructor is a diar pointer. In this example, there is no need for a 
named strstream. An anonymous constructor is more direct 

The inverse operation, taking a value and converting it to dtaracters that are stored into an array, is 
also posrible. For example, 

char s[32] ; 

ostrstxeai&(s,sizeo£(s)) « x « ends ; 

will store the character rqnesentation of x in s with a terminating null dtaracter supplied by the ends 
(endstring) manipulator. The iostream library requires that a size be supplied to the constructor and 
nothing is ever stored outside the bounds of the supplied array. In this an "output error" will 
occur if an attempt is made to insert more than 32 characters. 

In case it is inconvenient to preallocate enough space for foe string, a program can use an ostrstreamO 
constructor without any arguments. For example, suppose we want to read foe entire contents of a 
file into memory. 
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ifstreani in("infile’') ; 

// strstream vith e^namic allocation 
strstream inoore ; 

char c ; 

while ( incore in.get(c) ) inoore.put(c) ; 

// str returns pointer to allocated space 
char* contents * inoore.str() ; 

// once str is called space belongs to 
delete contents ; 

The file infile is read and its contents inserted into incore, ^laoe will be allocated usii^ die ordinaiy 
C-M- allocation (operator new) tnedtanism, and autmnatically increased as more diaracters are 
inserted. incore.strO returns a pcmter to the cunenfiy allocated ^>ace and also "fireezes" die 
so that no more characters can be inserted. Until inoore is fiozeit, it is the responsibility of the 
strstreamO destructor to free any space that mi^t have been allocated. But after Ae call to stxO, the 
space becomes the caller's responsn>ility. 

Predefined Streams 

There are four fnedefined streams, dn, cout oerr, and dog. The first three are connected to standard 
input, standard output, and standard error re^^ectivdy. dog is also cormected to stai^dard error but, 
unlike cerr, clog is buffered. That is, dtaracters are accumulated aitd written to staiwiard error in 
chunks, cout is also buffered. 

Frequently programs want to use eifiter standard input ard output or some external file depending on 
their command line arguments. One way is to use the predefmed streams and assign to them. 
Assignment of streams is not possible in general but the predefined streams have ^>ecial types wduch 
allow it. The reader is referred to the man pages for a discussion of the semantics of assigiunent A 
more flexible style is to use a pointer or reference to a stream: 

istceam* in - icin ; 

if ( iitfile ) in « new ifstzean (infile) ; 

*in « X ; 


Problems can occur when mixing code that uses iostreams with code that uses stdio. There is no coit- 
nection between the predefined iostreams and die stdio standard HLEs exc^t that they use die same 
file descriptors. It is possible to eliminate this proUem by calling 

ios::sync_with_stdio() 

which will coimect the predefined iostreams with the c o rresponding stdio FILEs. Such coruiection is 
not the default because there is a significant performance pe^ty when the predefined files are made 
unbuffered as part of the connection. 
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Format Control 


The default treatment of scalar types is that integral values (except char and unsigned char) are 
inserted in dedmal, pointers (except char* and unsigned char*) in hex, floats and doubles with 6 digits 
of precision and all without leading or trailing padding, char and unsigned char values are just 
inserted as single characters, char* and unsigned char* values are treated as {X>inters to strings (null 
terminated sequences of characters). The default treatment for extraction of integer types is decimal 
numbers with leading whitespace permitted. An optional sign (-f or -) is permitted, but without whi¬ 
tespace between it and the digits. Extraction is terminated by a non-digit character. Extraction for 
floating point types is similar except that the lexical possitMlities for floating point numbers are an 
optional sign followed (without interverting whitespace) by a number according to lexical rules. 

For many purposes fltese defaults are adequate. When they are not, the program can do more format¬ 
ting itself, or it can use the format control features of the iostream library. The exan^ies in this sec¬ 
tion use these features. 

Associated with each iostream is a collection of "format state variables" that control the details of 
conversioits. The most iRqx>i1ant of these is a long int value that is interpre te d as a collection of bits. 
These bits are declared as: 


enum 


{ skipws-01, // skip whitespace on input 

left-02, ci^t-04, intexnal-010, 

// padding location 
dec-020, oct-040, he»K)100, 

// conversion base 

showbase-0200, showpoint-0400, uppeccase-01000, 
showpos-02000, 

// m odifiers 

scientific-04000, fixed^^lOOOO 

// floating point notation 


1 ; 


These may be examined and set individually or coUectivdy. For exan^le, the iosrskipws controls 
whether leading whitespace is skipped by extractors. 


char c ; 

cin.setf (0,ios: :skipws) ; // turnoff skiving 

cin » c ; 

cin.setf (ios: :skipws,ios: :skipws) ;// turn it back on 

The second argument of setf indicates which bits should be set The first indicates what values they 
should be set to. 

Manipulators are declared (in iomanipdi) that will have an equivalent effect The above is equivalent 
to: 


cin » resetiosflags (ios:: skipws) 

» c 

» setiosflags(ios::skipws) ; 

resetiosflags resets (makes zero) the indicated bits and setiosflags sets (makes them 1) the indicated 
bits. 
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Commonly we want to save the flags (or other state variaWes) and restore their value later. Consider: 

long f - cin.flags 0 ; 

cin. setf (ios:: skipvrs, ios:: skipws) ; 

cin » c ; 

cin.flags(£) ; 

The variant of flags without an argument returns the current value. The variant with an argument 
stores the argument into the flags state variable. This code does the sante extraction as the p>revious 
code, but instead of arbitrarily leaving cin with skipping on it restores skipping to its previous 

of member functions is repeated for other state variaUes. That is, if svar is some state 
variable, and s is a stream, then ssvaai) returns flie current value of the state variable and s.svax<x) 
stores the value x into the state variable. 

Field Widths 

The default behavior of the inserters is to insert only as many characters as is necessary to represent 
the value, but frequently programs want to have fixed size fields. 

cout.width(5) ; 
cout « X ; 

will output extra space diaracters preceding the digits to Iwing the total number of inserted diaxacters 
to five. If the value of x will not fit in five diaracters, enough diaracters will be inserted to express its 
value. The numeric inserters never truncate. The width state variaUe mi^t be regarded as an impli¬ 
cit parameter of extractors because it is reset to 0 (which induces the default behavior) whenever it is 
used. 


cout.width(5) ; 

cout « X « " " « y ; 

will output X in at least five characters, but will use wily as many diaraders as necessary in outputting 
the separating space and y. 

The value of the width state variable is honored by the inserters of the iostream library, but user 
defined inserters are responsible for interpreting it themsdves. Fbr example, the Pair inserter defined 
previously does nothing special with widtti and so if it is non-zero wdien the inserter is raiifid ttie 
width will apply to the first int inserted, and not die second. If the inserter wants to honOT width its 
definition might look like: 

ostreams c^catoc«(ostEeanifi o. Pair p) { 
int w « o.widthO ; 
o.width (w/2) ; 

O « p.x « " • ; 
o . width (w/2- ((w+1) 11)) ; 

O « p.y ; 

return o ; 

1 

This inserts each number in half the requested widfli. 
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It is subtly awkward to mix calls to die wridthO member function with insertion operations. The 
manipulator setwO may be used. An alternative definition of the Pair inserter might be: 

iostxeamfi qperator«(iostrctain£ ios. Pair p) ( 
inc w « ios.vidthO ; 
return ios « setw(w/2) « pair.z « • • 

« setw(H/2't-((iH-l)si)) « pair.y ; 

} 

widdi is always interpreted as a minimum number of characters. There is no direct way to ^ledfy a 
maximum number of duuacters. In cases where a program wants to insert exactly a certain number of 
characters, it must do die woiic itself. For example, 

if ( strlen(s) > w ) cout.trrite(s,w) ; 
else oout « setw(w) « s ; 

will always insert exacdy w characters. 

width is generally ignored by extractors, whidi tend to rdy on the contents of the iostream to detect 
die end of a field. Ihere is, however, an important exception. The char* extractor interprets a non¬ 
zero width to be the size of the array. For example, 

chaz a[16] ; 

cin » setwfsizeof (a)) » a ; 

if ( iisspaoe (cin.peek 0 ) error ("string too long") ; 

protects the program in case there are sixteen or more visible characters. As a further measure of pro¬ 
tection, the extractor stores a trailing null in the last byte of the array when it stops because there are 
too many visible characters. This means that the nundier of characters e x tracted (not counting leading 
whitespace) will be at most one less than the specified widdi. 

Flags control whether padding (when it occurs) causes die fidd to be left or li^t justified. The fill 
state variable (whose initial value is a space) supplies die character to be inserted. 

cout.filK*) ; 

cout.setf (ios: :left,ios: :adjustfield) ; 

cout « setw(S) « 13 « ; 

cout.filK#) ; // set state variable 

cout.setf (ios: :rig^t,ios: :adjustfield) ; 

cout « setw(5) « 14 « "Xn" ; 

results in a line of output that looks like: 

13***,###14 


Conversion Base 

Integers are normally inserted and extracted in decimal notation, but this is controlled by flag bits. If 
none of iosrdec iosdhex, or iosroct are set the insertion is done in decimal but extractions are inter¬ 
preted according to the C-m- lexical conventions for integral constants. If iosnshowbase b set then 
insertions will convert to an external form that can be read according to these conventions. 
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For example. 


int X - 64; 

cout « dec « X « " " 

« hex « X « " " 

« oct « X « endl ; 
oouC.set£(ios: :shOHbase,ios: :stiOHbase) ; 
oout « dec « X « • " 

« hex « X « • • 

« oct « X « endl ; 

will result in the lines: 


64 40 100 
64 0x40 0100 


setfO with only one argument turns the specified bits on, but doesn't turn any bits off. 

Reading die lines shoivn above could be done by: 

cin » dec » x 
» hex » X 
» oct » X 

» xesetiosflagsdos: :base£ield) 

» X » X » X ; 

The value stored in x will be 64 for each extraction. The zesetiosflagsO manipulator turns of the 
specified bits in the flags. 

Miscellaneous Formatting 

As a precaution against looping, aero width fidds are considered a bad fmmat by the extractors. So if 
the next diaracter is whitespace and iossskipws is not set, die arithmedc extractors will set an error 
bit. 

The number of significant digits inserted by die floatir^ point (double) inserter is controlled by die 
precision state variable. The details of die conversion are furdier contrcflled by certain flags. The 
reader is referred to the man page for more details. 

It is good practice to flush ostreams appropriately. The flush and endl manipulators make it rdativdy 

ea^ to do so. Yet, there are circumstances in whidi some automatic flushing is appit^^te. This is 

supported by the ostream*' valued state variable tie. If Ltie is non~null and an istream needs more 
characters, the ostream pointed at by tie is flushed. Initially dn is tied in this fashion to cout so that 
attempts to get more characters from standard input result in flushing standard output This seems to 
handle most interactive programs reasonably well without imposing a large performance penalty on 
non-interactive programs and without creating different bdiavior when programs are connected to 
pipes rather than directly to a terminal. (Programs that won't work when their input or ou^t is con¬ 
nected to a pipe are one of the author's pet peeves.) The overheads implied ly tying are rdatively 
small when compared with "big" extractors (sudi as the aritiimetic ones) but may be large when sin¬ 
gle character operations are being performed. For this reason it is sometimes a good idea to break the 
tie by setting the state variable to 0. For example: 


iostream Examples 


3-17 





lostream Examples 


char c ; 

// break the tie to inprove performance of get. 
cin.tie(O) ; 

%rhile ( cin.get(c) ) cout.put(c) ; 


Manipulators 

A manipulator is a value that can be inserted into or e x tr a cted from a stream to cause some ^?ecial 
side effect That is, some side effect besides inserting a representation of its value, or extracting char¬ 
acters and converting them to a value. A parameterized manipulator is a function (or a member of a 
class with an operalozO) that returns a manipulator. Previous sectiorts contain examples of the use of 
manipulators utd parameterized manipulators. This section contains examples illustrating how to 
defirte manipulators. The predefined manipulators and macros discussed in diis section are declared 
in the header file iomanip Ji. 

A (plain) manipulator is a function that takes an istream& or ostream& argument, operates on it in 
some way, and returns it A (pointer to a) functicm of this type may be ex tra c t e d from or irtserted into 
a stream, re^pectivdy. 

Many examples of manipulators (such as flush or endD have already appeared in this paper. R>r 
example, a manipulator to insert a tab can be defined: 

ostceants tabfostreamc o) { 
zetuzn o « '\t' ; 

1 

cout « X « tab « y ; 

This seems over elaborate. Why not simply define tab as a character or string? One possible reason 
has to do witti the namespace. There can be only one (global) variable in a C-m- program rtamed tab 
but because of overloading fltere can be many functions witti that name. 

Another common use of manipulators is to shorten ttie long names and sequences of operations 
required by ttie iostream library. For example, 

ostzeamK fldfostzeains o) ( 

o.setf (ios: :showbase,ios: :shoid3ase) ; 
o.setf(ios::oct, ios::basefield) ; 
o.width(10) ; 
zetuzn o ; 

1 

cout « fid « z ; 


It is common for the function that manipulates a stream to need an auxiliary argument. setw() is an 
example of such a parameterized manipulator. To use parameterized manipulators the program must 
include iomanipli. 
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For example, we mig^t want to supply the value to be printed to fid in ti»e above. 

ostreanfi £ld(ostxeain& o, Int n ) ( 

long £- flags (ios: zshottoase I ios: :oct) ; 
o « set:w(10) « n ; 

flags (£) ; // restore original flags 

return o ; 

> 

GMANIP(int) fid(int n) { 

return CMRHIP(int) (fld,n) ; 

> 

cout « fld(23) ; 

OMANIP is a macro and OMANIPCint) expands to file name of a dass declared in iomanip Jl An 
OMANIP(int) insertion operator is also dedared in itmianipJi and is used in the example. Note that 
fid in the above is overloaded; it is both the function that manipulates the stream and a function fiiat 
returns an OMANIP(int). 

If we need parameterized manipulators for panuneter types other than int and long (whidi are 
declared in iomanipJi), fiiey must be dedarW. For example, suppose we want to read numbers fiiat 
may have a suffix. 

typedef long« Longref ; 
lOtAHIPdeclare(Longref) ; 

// Declares HAKIP (Longref), OMMIIP (Longref) , lOMAMIP (lAigref) 

// ZAPP(Longref), OAPP(Longref), IQAPP(Longref) 

istreams injcdstreanfi i, longs n) 

( 

// Extract an integer. 

// If suffix is present nultiply by 1024 
i » n ; 

if ( i.peekO — ')c' ) { 
i.ignored) ; 
n •- 1024 ; 

1 

return i ; 

} 

lAPP(Intref) injc - injc ; 

// lAPP(Intref) is the type of an Intref applicator 
// in k on right is function, on left variable 


long n ; 

cin » in_k(n) ; 

The lOMANIPdedarefn declares manipulators (and applicators) for type T. Because of the way the 
macro lOMANIPdedare expands, the argument must be an identifier. In this case a typedef is 
required to create manipulators for longdc. An a|^licator is something that behaves like a function 
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returning a manipulator. That is, it is a class with an opcntoiO member. 

^^unes we i^t a manipulator with more than one parameter. One way to achieve tixis effect is to 
<^i«^mampulator on a class. For example, a manipulator that can be used to repeat a string might 

cout « r^eat ("ab",3) « gndi ; 

to result in a line containing "ababab." A possible definition of repeat would be 

struct R^>eatpaic ( 

const char* s ; 
int n ; 


ICMANlPdeclace (Repeatpalc) ; 

static ostceanis c^eat (ostreamc o, itopaafpaiy p) { 

// insert p.s into o, p.n times 

for ( int n - p.n ; n > 0 ; —n ) o « p.s ; 

return o ; 

} 

OMANIP (Repeatpair) repeat (const char* s, int n) { 
R^eatpair p ; 
p.s-s ; p.n-n ; 

return OM»NIP(Repeatpair) (repeat, p) ; 

1 


Manipulators are a powerful and fledble method of extending the default inserters and extractors. 


The Sequence Abstraction 


The iostream library is buUt in two layers: The formatting layer discussed in previous sections, and a 
sequence layer based on the class streambuf. The formatting layer is responsible for converting 
between sequences of characters and various types of values and for hi^ level manipulations of the 
streams. The sequencing layer is responsible for producing and consumir^ those sequences of charac¬ 
ters. The most common way of using streambufe is with a stream. But streambuf is an independent 

class and may be used directly. ^ 

Abstractly, a streambuf represents a sequence of characters and two pointers into foat sequence, a get 
and a put pointer. These pointers should be thought of as pointir^ at foe locations either before or 
after diaractOT in foe sequence, rather than at ^ledfic diaracters. The sequences and pointers may be 
manipulated in a variety of ways, with the two fundamental ones being fefafoing the character after the 
get pointer, and storing a character in foe position after foe put p(mtex. Storir^ either r^ces any 
previous character at that location or, if the put pointer was at foe end of foe sequence, extends foe 
sequence. Other manipulations may move foe pointers in various ways. 
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For the examples of this section, we assume that there are two stieambufs, pointed at in and out 
Methods for constructing streambufs appear later, but it is ea^ enough to get at the streambuf associ¬ 
ated with a stream via xdbufO. So we assume that in and out have been initialized widt 

stceanbuf* in ■■ cin.xdbufO ; 
streambuf* out * cout.zdbufO ; 

An istream or ostream retains no information about the state of the associated stieambiif. For exam¬ 
ple a program may alternate between extracting characters from in and dm. 

The amplest operations are gettii^ and putth^ characters. A simple loop to copy diaracters from one 
streambuf to another would be: 

int c ; 

while (( c - itt->sbun|>cO) !« EGF ) ( 

if ( oat->spatc{e) •— EOF ) errca:(*oo^ut eczor") ; 

} 

sbumpcO fetches the character after dte get pointer and advances Ae get pcdnter over ttie fetched duur- 
acter. sputcO stores a diaracter into die sequence and moves die put pointer past iL Bodi functions 
report errors by letuming EOF, wdiich is why c must be dedaied an int nther dian a char. EOK 
returned while fetching tend to mean that die streambuf has run out of diaracters from die uldmate 
producer. EOFs returned when storii^ tend to signal teal e r r ors . Because, unlike iostreams, stieam¬ 
bufs do not contain any error state, it is possible that a store or fetdi miglit fail one time and succeed 
the next time it is tried. 

The streambuf class contains several difrerent member functkms for manqmlating die get pointer. The 
following loop repre s en ts a commcHi idiom: 

int c - in->sgetc() ; 
while ( c!"€Or !isspaoe(c) ) ( 
c • itt-’>sneztc() ; 

> 

It scans die streambuf looking for a whitespace diaracter (Le, one for whidi isspace b non-zero). It 
stops when it finds that character leaving it available for extraction. Thb b because sgetcO and 
snextcO do not behave the way many {nogrammers expect sgetcO retums the diaracter after the get 
pointer, but does not move die pdnter. snextcO moves the get pointer and then returns die diaracter 
that follows the new locadon. As usual bodi these funcdons return EOF to signal an error. 

The copy loop moved characters one at a time. It b possible to do larger chunks, as iru 
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static const Int Bufsize - 1024 ; 
char bu£(Bufsize] ; 
int p, g ; 
do { 

g > sgetn(bu£, Bufsize) ; 
p - sputn(buf, g) ; 
if ( p!-g ) error ("output error"); 
} irtiile ( g>0 ) ; 


sgetn(b^ atteii^>ts to fetdi n dtaracters from the sequence into die anay starting at b. Smilarly 
sptttn(b^) tries to store Ae n characters starting at b into the sequence. Both move tfte pointer (get or 
put respectively) over the characters they have f»t>cessed aivi return the number transferred. For 
sgetnO dus will be less than the number requested when die end of sequence is readied. When 
sputnO returns less dian the number requested, it indicates an error of some sort 

Buffering Exposed 

As die name suggests stzeambufs may iirqilement the sequence abstraction by bufrering between die 
source and sink of diaracters. This results in an unfortunate pun. Hie word ''buffer" is frequendy 
used informally to designate a stzeambuf, but it is also used to describe die chunking of diaracters. 
Thus, the oi^moron "unbuffered buffer" refds to a streambuf in which characters are passed to the 
ultimate consumer as soon as they are stored, and obtained from the ultimate producer whenever diey 
are retrieved. 

In li^t of the buffering provided by streambufs, the reader will not be surprised to discover diat 
arrays of characters ate used in the inq^ementatioti. The streambuf dass contains some member fuiK* 
dons that make die p re s e nce of such arrays visible to the program. With some effort , diey might be 
used to "break the ^traction," but the intended purpose is to deal with die ddays implidt in buffer¬ 
ing. 

The earlier example using sgetnO and sputnO to copy frmn in to out waits until Bufsize diaracters 
become available (or the end of the sequence is readied) before passii^ at^ to out If the source of 
diaraders has ddays (e.g., it is a person Qqnng at a terminal) and we want the characters to be passed 
on as soon as they become availa^; the program mi^ use operations on sin^ diaracters instead, or 
it might use an adaptive mediod sudi as: 

static const int Bufsize -• 1024 ; 
char bu£[Bu£size] ; 
int p, g ; 
do { 

itt->sgetc() ; // force a cbazactec in buffer 

g “ in->injavail () ; 

if ( g > Bufsize ) g • Bufsize ; 

g - in->sgetn(buf,g) ; 

p out->sputn(buf,g) ; 

out->sync() ; 

if ( p!*g ) error ("output error"); 

1 tdiile ( g > 0 ) 

in_avail returns the number of characters immediately available in the array. Calling sgetcO first 
fo^ there to be at least one such character (unless the get pointer is at die end of the sequence). 
Recall that sgetcO returns the next character, but doesn't move the get pointer. The code caUs S 5 mc() 
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after it has put characters into out thus causing these characters be sent to the ultimate ccmsumer. 

In some circumstances, such as when streambufe are being used for inter p rocess messages^ the chunks 
in which characters are produced and consumed may have significance. The above preserves these 
chunks provided they are less tiian Bufsize and titey fit into the arrays of in and out To ensure tiiat 
this latter condition is met the ccxle should provide large enough arrays explicitly with: 

char ibu£[Bufsize+8], obuf[Bufsize+8] ; 
in->setbuf (ibuf, sizeof (ibuf)) ; 
ouc->setbu£(obu£,8lzeof (obuf)) ; 

The calls to setbufO should be done before any fetches or stores are done. The arrays are ei^t larger 
than required the largest chunk to allow for various overheads. Of course, this code bdiaves prop¬ 
erly only when in delivers the duuacters in the ^{m^rriate diurtks. 

Using Streambufs in Streants 

The positions of the put pointer after qreratiorts that store characters, and position of the get pointer 
after operatiorrs that fetch characters are wdl defitted by the sequence abstraction. But fire loation of 
the get pointer after stores, arui the location of the put pointer after fetches is not Kfost specializations 
of streambuf (i.e., classes derived horn it) follow one of two patterns. Eititer the dass is queudike, 
which means that the put pointer arvi tire get pointer are indq>endent and moving one has no effect 
on tiie other. Or the dass is fildike, which means that udien one pointer moves tire other is adjusted 
to point to the same place. So a fildike dass bdtaves as if there were only orte pointer. Other possi¬ 
bilities are logically possible, but do not seem to be as useful. 

A queuelike streambuf, may be shared between two streams. For exarrqrie: 

strstreanbuf b ; 
ostzeam ins(Cb) ; 
istream extc(ab) ; 

while (_) { 

iris « X ; _; 

excc » X ; ; 

1 

This example esq^lidtly uses tire stistreambuf dass (declared in stzstieamJi) whidi is also used (im^di- 
dtly) by the btrstream arid ostrstieam classes. The btreamO arid ostzeamO constructcws require a 
streambuf argument. They use that streambuf as a producer or consurrier of duuacters. The duuac¬ 
ters irtserted into ins may bter be extracted fiom extr. If an attempt b ever made fo extract more 
characters than have been irtserted, the extraction will fail If more characters are bter inserted, cxtr's 
error state can be deared and die extraction retried. 

Because of the dynamic allocation performed stcstreambufs tfie queue b unbounded, but diere b a 
serious drawback. Space b not redbimed until b b destroyed. 
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Deriving New Streambuf Classes 


The streambuf class is intended to serve as a base Althou^ it contains members to manipulate 
the sequences, it does not contain ai^ mechanism for producing or consuming characters. These must 
be provided by a derived cl ass. The iostream Ubraiy contains several sudi derived streambuf 
but a program may define new ones. 

The members of a dass fiiat are intended for use by derived are protected, and the data struc¬ 
ture as seen by a derived dass is said to be ttie protecte d interface of die streambuf Ihis 
abstraction exposes the details of the array management that is implidt in the buffering provided by 
streambufs. It consists of two parts. The first part is member funrtrms of streambuf dut permit 
access to and manipulation of die arrays and pmnters used to ioqilement the sequence abstraction. 

The second part is virtual members of streambuf that must be suf^died by the derived 

The prindple exanqile of this section vrill be the io^lementation of fofouf, whose dedaration looks 
like: 

typedef int (*aetian) (diar* b, int n, openjeode at) ; 

class fetbuf : public steaanhuf { 
public: 

fetbuf taction f,open_aiode aO ; 
private: ... 

1 ; 

When called with m=iossout, an actionO function processes the n characters starting at b. When 
called with msiosdn, it stores n diaracters starting at b. It returns non-zero to indicate success and 
zero to indicate failure. 

The declaration of fcdiuf looks like: 

class fetbuf : public stzeaaibuf ( 

oonstzuctoc 
ai) ; 

data aienbecs 


virtuals 

int undecfloirO ; 

stzeaahuf* 

setbuf(char*, int, int) ; 
int syncO ; 


public: // 

fetbuf (action a, apen_aiode 

private: // 

action fet ; 
openjBode 

diar saBllIl] ; 

pcotected: // 

int overflow (int) ; 


1 ; 
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The constructor just initializes the data elennents. The acticm function a will be called only in modes 
compatible with m. 

fctbuf:: fctbuf (accioi a, ^)en_n)Dde m) 

: £ct(a}, iiiDde(m) { } 


The virtual functions define detaUs that make fctt>uf() bdtave properly. The streambuf protected 
interface is orgaitized around three areas (char arrays), the holding area, the get area, ai^ die put area. 
Characters are stored into the put area and fetched from die get area. 

As characters are stored in the put area, it shrinks untQ diere is no more space available If an attempt 
is made to store a character when die put area has no q>aoe, a new area must be estaUished. Befine 
that can be done the old chaiacters must be ccmsumed. Both diese tasks are die responsilniity of the 
oveiflowO function. Similarly, the get area is shrunk fetdies and is eventuaUy empty. If more 
diameters ate needed die nndexflowO function must oreate a new get area. Bodi ovodowO and 
ondeeflowO will use the holding area to initialize die put or get area (respeedvdy). 

setbuf 

The virtual function setbuf is called user code to oder an array for use as a holding area. It can 
also be used to turn off budering. 

streambuf* fctbuf:: setbuf (char* b, int len) 

{ 

if ( based ) return 0 ; 

if < b!«0 len > sizeof (small) ) { 

// set up holding area 
setb(b,b4-len) ; 

} 

else ( 

// Use a one character array to achieve 

// "unbuffered* actions. 

setb(small,small-fsizeof(small)) ; 

1 

setp(0,0) ; // put area 

setg (0,0,0) ; // get area 

return this ; 

1 

The actions of this function are: 

■ based points to the first character of die holding area. If a holding area has already been set up 
(base non-zero) a new one cannot be established and sedmfO returns a null pointer as an error 
indication. 

■ If an array is supplied and is sudidendy large, sedK) is called to set up the pesters to die hold¬ 
ing area. Its first argument becomes base, die first char of die holding area, and its second 
becomes ebuf, the char after the last Otherwise the fctbuf will become unbudered. This is 
noted by setting up a one diaracter holding area. 
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■ Finally the pointers related to the put area are set to 0 by setpO and the pointers related to the 
get area are set to 0 by se^O. 
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overflow 

The virtual function ovexflowO is called to send some diaiacters to the consumer, and establish the put 
area. UsuaUy (but not always) when it is called, the put area has no ^»ce remaining. 

int fctbuf::overflow(Int c) { 

// check that output is allowed 
if ( ! (nDde&los: :out) ) return ; 

// Make sure there is a holding area 
if ( allocate()«-GOF ) return EOF ; 

// Veri^ that there are no characters in 
// get area. 

if ( gptrO tt gptrO < egptrO ) return BOF ; 

// Beset get area 
setg (0,0,0) ; 

// Make sure there is a put area 
if ( IpptrO ) setp(based,base0) ; 

// Determine bow nany characters have been 
// inserted but not omsuned. 
int w - pptrO-phase 0 ; 

// If c is not BCX* it is a character that oust 
// also be consumed, 
if ( c !- BM* ) { 

// fie always leave space 
•pptrO - c ; 

1 

// constsne characters. 

int ok • (*fct) (pbaseO, w, ios::out) ; 

if { ok ) { 

// Set vp put area. Be sure that there 
// is space at end for one extra daaracter. 
setp(base0,ebu£0-1) ; 
return zapeof(c) ; 

I 

else { 

// Indicate error. 
setp(0,0) ; 
return BOF ; 

1 

) 

Sonte explanations of this code 
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■ It first tests for various error conditions, such as trying to do insertion when there are characters 
that have been produced but not extracted. This is a proUem becaiise the code only uses one 
area to hold characters for insertion atKi extraction. It would also be possible to igiK>re this con¬ 
dition and just throw away the dtaracters or a more elaborate version of fctbuf mi^t use 
sepcuate areas for insertion and extraction. 

■ allocated is a part of the streambuf protected interfoce. If no reserve area has previously been 
specified it allocates heap space. 

■ phase is the value of pptr established by the last call to se^). As characters are stored, pptr is 
ntoved so that it always points to ttte first untised dtaracter. Ihus the characters between phase 
and pptr have been stor^ aitd itot coitsumed. TliQr are now sent to the cortsumer. 

■ The value returned by die oortsumer is dtedced to verify dtat it has been able to cortsume all the 
characters that were passed to it If itot, there is no put area and EOF is returned. 

■ When all has gone wdl die put area is established by setpO whose first argument becomes pptr 
(pointing to the first char of the put area) and whose sectmd becomes epptr (pointirg to the char 
after die last char of the put area). In this case when no errors have occurred the whole holding 
area minus the last diaracter is used as a put area. The last diaracter will usually be filled in by 
the character supplied to the next call to oveiflowO. 

■ Finally, if all has gone well, c is returned unless it is ^F. If c is EOF something dse must be 
returned because EOF is returned to signal an error. The macro zapeofO deals with this con¬ 
tingency. 


underflow 

The underflow function is called when characters are needed for fetdiing and none are available in the 
get area. Its general outline is similar to overflowO, but it deals with the get area radier than the put 
area. 

int fctbuf:: underflow 0 { 

// Check that input is allowed 
if ( ! (node&ios::in) ) return EGF ; 

// Make sure there is a holding area, 
if (allocated—G^) return BOF ; 

// If there are characters waiting for output 
// send them ; 

if ( pptrO M PPtrO > phased ) over£low(BK*) ; 

// Reset put area 
setp(0,0) ; 

// Setup get area ; 

if { blend > 1 ) setg(based,based+l,ebufd) ; 
else setg(based ,based ,ebufd) ; 

// Produce characters 

int ok - (*fct) (based,blend,ios::in) ; 
if ( ok ) ( 

return zapeof(*base()) ; 
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) 

else { 

setg (0,0,0) ; 
return EOF ; 

1 

} 

Some explanations: 

■ EOF is returned inunediatdy if we aren't supposed to do ii^nit or if a holdii^ area cannot be 
allocated. 

■ allocateO is called to make sure tfiat Aere is a holding area. 

■ setgO is used to establish the get area where fct will be asked to store duracters. Its first argu¬ 
ment sets up a pointer, eback, that marks the limit to which patt>adc can move gptr. The 
second argunnent becomes gptr, and die last becomes egptr, pointir^ at the char after the last 
char containing values stored by die producer. 

■ blenO returns the size of die holdii^ area. It may be as smaU as 1. 

■ If the action function indicated success underflowO returns die first character. It is left in the get 
area and may be extracted again. z^ieofO is used to make sure that the returned result b not 
EOF. If zapeofO were omitted thb mi^t occur on a madiine in which diazs are signed and 
EOF is -1. 


sync 

The virtual function ^cO is called to maintain synchronization between the various areas and die 
producer or consumer. It b also called by die streambufO destructor. 

int fctbuf:: sync () 

{ 

if ( gptrO s< egpcrO > gptrO ) { 

// no «ay to zetuzn characters to producer 
return ; 

) 

if ( pptrO i^rO > pbaseO ) { 

// Flush waiting output 
return over£low(B0F) ; 

1 

// nothing to do 
return 0 ; 

} 


The virtual functions defined above inqilenient a correct streambuf class. A possiUe refinement would 
be to provide implementations of the virtual xsputnO and xsgetnO functions. These functions are 
called when chunks of characters are being inserted and extracted respectively. Thdr debult actions 
are to copy the data into the buffer. If they were defined in the fctbof class they could call the func¬ 
tions diret^y and avoid the extra copy. 
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Extending Streams 


There are tw kinds of rea»ns to extend the basic stream dasses. The first is to specialize to a partic¬ 
ular kind of streambof and the second b to add some new state variables. 

Specializing istream or ostream 

When Ae iostream Ubrary is specialized for a new source or sink of characters the natural pattern is 

Firetdenve a class from streambuf, such as fctbof in the previous section. Then deriw dasses 

from whichever of istream, ostream, or iostream b appropriate. For example suoDose we 

thb with the fcfouf class defined in die previous section. The streains mig^t ^ ^definitions: 

class fccbase : victual public ios ( 
public: 

fctbaso (action a, cpen^node m) 

: buf(a,n) { Init(£buf) ; } 

private: 

fctbuf buf ; 

) ; 


class ifctstream : public fctbase, public ( 

public: 

ifctbase (action a) 

: fctbase(a, ios::in) { ) 

1 ; 

class ofctstreaxn : public fctbase, public { 

public: 

ofctbase(action a) 

: fctbase(a, ios::out) { } 


class iofctstream : public fctbase, public iostream { 
public: 


} 


iofctstream (action a open_aiode m) 
: fctbase(a, m) { ) 


Dot^Uoi^ ftom los are virtual so that when die dass hietardiy joins (as it does in iofobtream) diere 
will be only one copy of the error state information. Because the derivation from ios is virtual an 
argument cannot be suppUed to its constructor. The streambuf is supplied via iossinitO, which is a 
protected member of ios intended precisely for thb purpose. 

Extending State Variables 

In many circumstances we would like to add state variables to streams. For example, suppose we are 
printing trees and would like to have an indentadon levd with an ««*«»«». 
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int xdent - ios: :xalloc() ; 

// generate a unique index 

ostreaznc indent (ostreanfi o) { 

// manipulator that inserts newlines and 
// appropriate nunber of tabs 
o « 'W ; 

int count > o.iword(xdent) ; 
while ( count— > 0 ) o « '\t' ; 
return o ; 

} 

ostreamfi redent (ostreamK o, int n) ( 

// parameterized manipulator that 
// indentation level 
o.iword (xdent) n ; 

> 

OAPP(int) redent « red en t ; 

o.iword(xdent) is a reference to the xdent'A integer state variaUe. Each call to returns a 

different index. The index may dten be used to access a wwd associated %vith the stream. Hie reason 
for calling iosnxalloc to get an index rather dian just piddt^ an arbitrary one is that it allows oomlrin- 
ing code dukt uses the indentation level widi code diat rru^ have extended die formatting state vari¬ 
ables for some other purpose. 

A subtle problem occurs in die above exarr^le because xdent is initialized by a function call What if 
indentO or redentO were called before xdent was initialized? Can diat happen? Yes it can. It can 
happen if indentO or redentO is called from inside a constructor that is itself to initialize some 
variable with program extent Problems with order of initialization when doing I/O in constructors 
are corrunon. The solution relies on "tridcs" to tore initialization order. In this we would put 
into the header file containing the dedarations of indentO and zedentO: 

static class Indent_init { 
static int count ; 

public: 

Indent_lnit () ; 

~Indertt_iiiit 0 ; 

} indentjLnit ; 

Each file that indudes this header file will have a local variaUe indent_init diat has to be initialized. 
Because this variaUe is declared in the header its initialization will ocru r early. 

The definition of the constructor and destructor looks like: 
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static lostream init* io ; 


Indeiit_init:: Xnden.t_init () 

{ 

// count keeps track of the difference between bow 
// many constructor and destructor calls there are 
if ( count-H- > 0 ) return ; 


// This code is executed only the first time 
io -• new Iostream_init ; 
xdent ios: :xalloc() ; 

} 


Indent_init:: ~I n d ent_ lnit () 

{ 

if ( —count ) > 0 ) return ; 

// This code will be executed the last 
delete io ; 

> 


The iostream library uses this idea itself. The oonstructcx’ for lostreant^init causes the iostream library 
to be initialized the first time it is called. It also keeps track of how mimy times the constructor is 
called and will do finalization operations on various data structures the last tinne it is called. It is 
therefore important that any values of type Iostream_iiiit that are constructed by a program are even¬ 
tually deleted. This is tiie purpose of having an lndent_imt destructor; even though tftere are no final¬ 
ization operations assodat^ with indentation, it must ddete io. 



Comparison of lostreams, Streams, and Stdio 


The stdio library served C programmers well for many years. However, it has several deficiencies: 

■ The use of functions, like printfO, that accept variable numbers and types of arguments mean 
that type cheddng is subverted at an in^rtant point in many programs. 

■ There is no mechanism for exteiviing it to user defined dasses. The only way to add new for¬ 
mat specifiers to printfO is to reimplement iL 

■ The mechanism is dosely tied to file I/O. sprintfO exj^fly extertds it to incore operations, but 
there is no general method for creating alternate sources and sirtks of data. 


After stdio, the rtext stage of devdopment was tire stream library. Its most significant iimovation was 
the introduction of insertion and extraction operatiorts. The first two problems with stdio were 
elegantly solved. It was in use by C-m- progranuners for several yeaas. But the stream library had 
problems of its own: 


■ The mechanism for creating sources and sinks of characters (streambuf dass) was rK>t docu¬ 
mented or desigrwd for exterrsion. 
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a The full range of UNIX file operations was not supported. In particular there were no lepoa- 
tioning operations (seeks). 

a There was only limited control over formatting. Programs frequently reverted to pzintfO like 
functions to specify alternative formats for numbers. A fixed size area was allocated for convert- 
ing values to strings and then outputting file strings. Althou^ it was not a problem in {vactioe, 
in theory this buffer was subject to overflows. 

The iostream Iforary presented in this document has resolved tftese problems. It is r^tivdy ttew, and 
whether significant problems will emerge in the future is not yet Imown. Some apparent deficiencies 
are: 


a There is no way to determine if a (»oduoer has duracters available, and no way to select input 
from one of multiple sources. This is, of course, also a deficiency of stdio and streams. 

a There is no way to process data in the bufiiets without copyir^ them out This extra copying 
step can be expensive when simple operations (e.g., scanning for a ^>ecific duuacter) are being 
peiformed. 

a Some formatting operations tend to be wordier than the equivalent stdio operations. This is 
compensated for by foe ability to define manipulators and inserters. 


Converting from Streams to lostreams 


The iostream library is mostly upward compatible wifo the older stream library, but there are a few 
places where differences may afiect programs. This s^on dij y n sses those differences. 

The major conceptual difiererKe is that in the iostream library, streams artd streambufs are regarded 
solely as abstract classes. The old stream classes (novided certain specialized bdiaviors, ^redfically 
incore formatting and file I/O. In the iostream library these are su pport ed soldy fom ugh derived 
classes. 

The old stream library declared every fomg in the header file streaiiLlL The iostream library 
iostreairuh and some other headers. For compatibility a streamJi is supf^ied foat indudes i ostr»a«" ^ 
and other headers that are required for compatibility and defines a variefy of items whose names are 
different in the iostream and stream Utnaries. 

streambuf Internals 

The internals of foe streambuf class in the stream library were all public Any program that rdies on 
these internals will break because they are different (aixi private) in foe iostream library. 

How to derive trew streambuf dasses was not documented in the stream lOxary. But it is such a 
natural idea to do so that numy programs do it Omvertir^ fitese programs to the iostream library 
may require changes in the derived overflowO and undetflowO functiotts. The furtctionalify of these 
functions in foe iostream library is essentially the same as in the stream library. But because foe inter¬ 
nals of streambuf have changed, some code changes will pobably be required. In particular the code 
will have to use the (protected) streambuf member functions setbO, setg(), arul setpO instead of 
directly manipulating the pointers. 
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Incore Formatting 

In the stream library the use of arrays of dtaracters as sources or sinks was supported as Ae default 
behavior of streambuf. AlAough some atten^t to preserve the default behavior is made by the ios- 
tream Ubrary these uses of a streambuf are considered obsolete. The support of incore operations is 
specifically Ae re^nsibility of the stcstreambuf declared m strstreamii. streambuf created for this 
purpose can usuaUy be replaced directly by stxstreambufs that have equivalent behavior. The stream 
usage: 


char* bu£[10] ; 
stxeanbuf b(bu£,10) ; 


is equivalent to the iostream: 


char* bufflO] ; 
strstreanbuf b(bu£,10) ; 

and the old method for initializing a streambuf for extraction: 

char* bufllO] ; 
streambuf b ; 
b.setbu£(bu£,10,bu£4’5) ; 

is equivalent to the iostream method: 

char* bufllO] ; 

strstreambuf b(buf,10,buf't-5) ; 


Frequently these uses of streambuf do not appear exi^dfly m the program but are Ae consequence of 
using certain constructors of istrcam and ostream. These constructors are supplied m Ae iostream 
library, but are cortsidered obsolete. The equivalerU forms using strstream should be 

The old method of storii^ a formatted value into an array: 

char* buf [10] ; 
ostream out (10, b) ; 

is r^laced by: 

cAar* bu£[10] ; 
ostrstream out (b, 10) ; 

Note that Ae order of Ae arguments is reversed. The new order creates nnote oonsisteiKy between 
various uses of strstreams. 

The old rrtethod of extracting a formatted value from an array: 

char* buf[10] ; 
istream in(10,b) ; 

is replaced 
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char* buf[10] ; 
istrstream ln(b, 10) ; 


The old istreamO constructor allowed an optional extra argument to ^)ecify skipping of white^ce. 

In the iostream library this is part of a greatly e>q>anded collection of state variables and so an extra 
argument is not provided for the istxstreamO constructor. However, the obsolete form of istreamO 
constructor continues to accept these optional arguments. 

Fiiebuf 

Both libraries contain a fiiebuf dass for using streams to do I/O. It is declared in fstreamii in Ae ios¬ 
tream library. The stream library had ccmstructors that im{^ied Ae use of filebnfs. In the iostream 
library these constructors are replaced by constructors of certain derived Ihe old usage; 

int £d ; 

istzean in(£d) ; // file descriptor 

ostream out (£d) ; // file descriptor 

is replaced by: 

int fd ; 

ifstream in(fd) ; // file descriptor 
ofstream out (fd) ; // file descriptor 

The optional extra arguments of Ae stream constructors (for qKdfyir^ whitespace skipping and 
“tying") are not supported. The equivalent functionality is sui^orted by format state variaUes. 

Interactions with stdio 

The libraries difier sigiuficantly m the way they mteract wi A stdio. Ihe old stream header streanuh 
included stdioA and some stream data structures could contain a pomter to a stdio FILE, hi Ae ios¬ 
tream library specialized streams arul streambufo (declared m stdiostreamJO are provided to make the 
connection. 

The old usage: 

FILE* stdiofile ; 
fiiebuf fb(stdiofile) ; 
istream in (stdiofile) ; 
ostream out(stdiofile) ; 

is replaced by: 

FILE* stdiofUe ; 
stdiobuf fb(stdiofile) ; 
stdiostream in (stdiofile) ; 
stdiostceam out (stdiofile) ; 

In the old library the predefined streams dn, cout, and cetr were directly cormected to the stdio FILEs 
stdin, stdout, and stderr. I/O was mixed dtaracter draracter. Further, these streams were unbuf¬ 
fered in the sense that insertion and extraction was done by doing character by character puts and gets 
on the corresponding stdio FILEs. In Ae iostream library Ae predefined streams are attached directly 
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to file d^cnptors rather than to the stdio streams. This means that for output the characters are mixed 
only as flushes are done and the input bu^er of oi>e is not visible to ti»e other. 

In practice the biggest problems seem to come from attempts to mix code that uses stdout with code 
that uses couL The best solution is to cause flushes to be inserted whenever the program switches 
from one library to the other. An alternative is to use: 

ios:: sync_with__stdiio () ; 

This car^ the predefined streanw to be connected to the corresponding stdio files in an unbuffered 
mode, ^e major drawback of ttiis sdution is the large overheads associated with insertion of duuac- 
ters in ftis mode. TypicaUy insertion into cout is slowed ly a factor of 4 after a call of 
sync_with_stdio(). 

The old stream library contained some "stringifying" functions that were called with various argu- 
^ts and returned a string. These are declared in streamJi and available primarily for compatibility. 
The only such formatting function that seems to provide a significant functionality that is not easily 
available in the iostream library is formO, which allows printfO like formatting. In fact, foimO is hist 

a wrapper for calls to spzintfO. The programmer can easUy write manipulators and inserters that do 
the same thing. 

Assignment 

In the old library it was possible to assign one stream to another. This is possible in the iostream 
Ubrary only if the left hand side is declared to be an assignable dass. A general assignment cannot be 
allowed because of the interactions of derived c lass es . What, for exam{fle, ^uld be the effect of 
assigning an ifstream to an ististream? Most programs that use this feature can be converted by using 
a reference or pointer to a stream. The old usage: ® 

ostream out ; 
out - cout ; 
out « X ; 

can be replaced by: 

ostream* out ; 
out * cout ; 
out « X ; 


on 


ostream_%rith__assign out ; 
out scout ; 

•out « X ; 


char Insertion Operator 

The stream library did not contain an insertion operator for char. So inserting a char was taken as 
inserting an inte^r value, and it was converted to decimal. This omission was due to problems with 
overload resolution in earlier versions of the C++ Language System. Any old code such as: 
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char c ; 
cotit « c ; 

may be replaced by: 

char c ; 

cout « (Int)c ; 
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(C-4-«- Complex Math Libniy) 


CPLXJNTRO(3C++) 


NAME 

complex - introduction to C-m- complex mathematics libraiy 
SYNOPSIS 

#include <complexJi> 
class complex; 

DESCRIPTION 

This section describes functions and operators found in Ae C>m> Cbmplex Madiematics 
Libraiy, libampkxja. Tltese functions are not automatically loaded by the C++ compiler, CC(1); 
however, ^ link editor searches dus libraiy under dte -komplex option. Dedaiations for 
these functions may be found in the #include file <coiiiplexJ&. 

The Cbnq>lex Mathematics libraiy in^>lements the data type of comfriex nunfoen as a 
complex. It overioads die standard input, output, arithmetic; assignment, and conqarison 
operators, discussed in the manual pages for c{tops(3C++). It also overioads the standard 
exponential, logaridun, power, and square root functions, discussed in qdxexp(3C++), and die 
trigonometric functions of sine, cosine, hyperbolic sine, and itypeibolic cosine, in 

cplxtrig(3C++), for the class conplex. Routines for convertij^ between Carterian and po lar 
coordinate systems are discussed in cartpol(3C++). Error handing is describedin 
cplxerr(3C++). 

FILES 

INCDIR/complexJi 
LIBDIR/Iiboomplex.a 

SEE ALSO 

cartpol(3C++), cpbcerr(3C++), cpbcops(3C++), cidxexp(3C++), and cpbctrig(3C++). 

Stroustrup, B., "Complex Arithmetic in C++," C++ Translator Rdease 2.0 Documentation. 
DIAGNOSTICS 

Functions in the Complex Madiematics library (3C++) may return die conventional values (0, 
0), (0, ±HUGD, (±HUG^ 0), or (±HUG^ ±HUGE), when the function is undefined for the 
given arguments or udien the value is not lepiesentaUe. (HUGE is the largest-magnitude 
single-predsion floating-point number and is defined in the file <inaflLh>. The header file 
<inadiii> is included in die file <complexJi>.) In these cases, die external variable arm (see 
intro(2)] is set to the value EDOM or ERANGE. 
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(C++ Complex Math library) CARTPOL(3C++) 

NAME 



cartesian/polar - functions for the C-t'-t- Comfriex Matti Library 
SYNOPSIS 

#inclade <coinplexli> 
class complex { 


public 


}; 

Mend double absfcomplex); 

Mend double aigfcomplex); 

Mend complex oonjfcon^rlex); 

Mend double ima^complex); 

Mend double turrmfcomplex); 

Mend complex polarfdouble, doable s O); 

Mend doable reaKcootylex); 


DESCRIPTION 

The following functions are defined for coatplez, where: 

— d, m, and a are of type integer and 
— X and y are of type coo^lez. 

d * abs(x) Returns the absolute value or magnitude of x. 


d s norm(x) 

Returns the square of the magnitude of x It is faster than abs, but more likdy 
to cause an overflow error. It is interuled for conq^arison of magnitudes. 

d s axg(x) 
y s conj(x) 

Returns the an^e of x, measured in radians in dte range -rc to x. 

Returns die conjugation of x. That is, if x is (red, inug), then conjfx) is (red, 
-imag). 


y s polaxfnv >) Creates a complex given a pair of polar coordinates, magnitude m, and angle 
a, measured in radians in die range -a to ic. 

d s reaKx) Returns the real part of x. 

d s imagfx) Returns the imaginary part of x. 

SEE ALSO 

CPLXJNTRCX3C++), cpb{en<3C++), cfrixops(3C-M>), cpIxexp(3C-M-), and cplxtrig(3C-M-). 
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(C-M- Complex Matii libniy) 


CPLXERR(3C-m-) 


NAME 

complex_error - eiTor*handling function for the €-«-«■ CoR^ylex Math libiaiy 
SYNOPSIS 

#include <complexJi> 

class c_exception 

{ 


int 

*yp«? 

diar 

*name; 

complex 

aigl; 

complex 

azgZ; 

complex 

zetval; 


public 


c_exception( char *iw const coiiq>lexdc al, const complex^ a2 « coniplex_zero ); 


friend int 


complexjencoK c_exoeption& ); 


}; 


Mend complex 
friend complex 
friend complex 
friend complex 


exp( cmnplex )j 
sinh( complex ); 
cosh( complex h 
log( con^rlex ); 


DESCRIPTION 

In the following description of the complex error handling routine, 

— d is of type double and 
— X is of type con^lex. 

d s complex_ezroi:(x&) Invoked functions in die C-m- Complex Mathematics library 

when errors are detected. 


Users may define their own procedures for handlir^ errors, by defining a function named 
complex_eiror in their programs, complexjeiror must be of the form described above. 

The element type is an integer desoibitig die type of error that has occurred, from die follow¬ 
ing list of constants (defined in the header file): 

SING argument Angularity 

OVERFLOW overflow range error 

UNIXRFLOW underflow range error 

The element name points to a string containing die name of die function dut incurred the 
error. The variaUes argl and argZ are die arguments with which the function was invoked. 
Retval is set to the default value that will be returned by the function unless die user's 
complex_eiror sets it to a di^erent value. 

If the user's complex_enor function returns non-zero, no error message wiU be printed, and 
ermo will not be seL 

If complex_enor is not supplied by the user, the default error-handling procedures, desoibed 
with the complex math functions involved, will be invoked upon error. These procedures are 
also summari^ in the table below. In every case, ermo is set to EDC^ or ERANGE and the 
program continues. 

Note that complex math functions call functions included in the math library which has its 
own error handling routine, matheniSM). Users may also override diis routine by supplying 
their own verAon. 
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CPLXERR(3C++) 



DEFAULT ERROR HANDUNC PROCEDURES 


Types of Errors 

type 

SING 

OVERFLOW 

UNDERFLOW 

amo 

EZX>M 

ERANCE 

ERANCE 

EXP: 




real too Urge/snudl 

- 

tta±H) 

C0.0> 

imag too large 

- 

c.a) 

- 

WG, 




arg ■ (0, 0) 

KidiO) 

- 

- 

SINH: 




real too large 

- 


- 

imag too large 

- 

<0,O) 

- 

COSR* 




real too large 

- 

tlHlH) 

- 

imag too large 

- 

OeQ) 

- 



ABBREVIATIONS 

M 

Message is printed (EDOM enor). 

(H,0) 

(HUGE, 0) is returned. 

(±H.±H) 

(^UGE, ±HUCE) is returned. 

(0,0) 

(0,0) is returned. 


SEE ALSO 

CPLX.INTRCK3C++), mathenOM), car^l(3C++), q>lxops(3C++), q>lxexp{3C-M-), and 
cpIxtrig(3C++). 
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CPLXEXP(3C+-t-) 


(C-M- Complex Math libiaiy) 


CPIJ0EXP(3C++) 


NAME 

exp, log, pow, sqrt - exponential, logarithm, power, square foot functions for the C-t-* complex 
library 

SYNOPSIS 


#include <complexii> 


class complex { 


public 


friend complex 

expCcomplex); 

friend complex 

lo^complex); 

friend complex 

powfdouble, complex); 

friend complex 

powfeomplex, int); 

frieiui complex 

pow<eomplex, double); 

friend complex 

pow(complex, complex); 

friend complex 

sqrtfcomplex); 


}; 


DESCRIPnON 

The foUowing mafo functions are overloaded by the ooitq^ libraiy, where: 

— X, y, and z are of type con^lex. 

z s exp(x) Returns . 
z s log(x) Returns the natural logarithm of x. 
z = pow(x, y) Returns . 

z = sqrtfx) Returns foe square root of x, contained in foe first or fourfo quadrants of foe 
complex plane. 

SEE ALSO 

CPIXINTRO(3C++), cartpol(3C++), qplxeiT(3C++), cpba)ps(3C++), and q>lxtrig(3C++). 
DIAGNOSTICS 

exp returns (0,0) nfoen foe real part of x is so small, or the imaginaiy part is so large, as to 
cause overflow. When the real part is large enough to cause overflow, txp returns (HUGE, 
HUGE) if the cosine aiKi sine of the imaginary part of x are positive, (HUG^ -HUGD if the 
cosine is positive and foe sine is not, (-HUG^ HUGE) if flte sine is positive and the cosine is 
not, and (-HUG^ -HUGE) if neithv sine or cosine is positive. In all these cases, errno is set 
to ERANGE. 

log letunns (-HUGE, 0) and sets ermo to EDOM when z is (0, 0). A message indicating SING 
error is printed on foe standard errOT output. 

These enor-handling procedures may be charged wifo foe functitm complex^eitor 
(cplxerr(3C++)). 
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(Ci-f Complex Math Libniy) 


CPLX0PS(3C4-*^) 


NAME 

complexjoperators: opoatois for foe C-m- oomf^ mafo library 


SYNOPSIS 

#inclttde <ooinplexJi> 


class complex { 

public 

friend complex 
Mend complex 
Mend complex 
Mend complex 
Mend complex 


Mend int 
Mend int 


void 


void 


void 


void 


}; 


<^>crator«<cofiiplex, ceoqrlex); 
t^crator-icomplex); 
opcntot^ioompiex, complex); 
opecator*(compleXr conqtlex); 
opecatoi/icoiiiplei^ complex); 

opecatotn(complex, cMoplex); 
operatorMcompkn, complex); 

operatorWcooiplex); 

ppecator-s(complex); 

opecatoE*s(coiiq>lex); 

operatOEMcomplex); 


DESCRIPTION 

The basic arithmetic operators, coii^>arison operators, and assignmeitt <^>eratois are over¬ 
loaded for complex numbers. The operators have their conveittioiud fvecedenoes. In the fol¬ 
lowup descriptions for complex operators, 

— X, y, and z are of type complex. 

Arithmetic operators: 

z = X y Returns a cmnplex whidt is foe arithmetic sum of complex numbers z arxi y. 

z = -X Returns a complex whidt is foe arithnnelic negation of comfdex number x 

z s X - y Returns a complex which is foe arithmetic difierertce of complex nunibers z 

and y. 

z s X * y Returns a complex ufoidi is the arithmetic product of ootrqtoc numbers z 
and y. 

z = X / y Returns a complex whidi is the arifometic quotient of conqdex numbers z 

and y. 

Comparison operators: 

X ss; y Returns non-zero if oonq>lex number z is equal to complex number y; returns 

0 otherwise. 

X y Returns non-zero if complex ruimber z is itot equal to coriqdex number y; 

returns 0 otherwise. 

Assigiunent operators: 

X y Complex number z is assigned foe value of foe arithmetic sum of itsdf and 

complex number y. 

X -= y Complex number z is assigited foe value of foe arifometic difterence of itsdf 

and complex number y. 
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(C4-*- Complex Math Libcuy) 


CPLXOPS(3C-m-) 


* ~ y Complex number x is assigned the value of the auithmetic product of itself 

and complex number y. 

X /= y Complex number x is assigned the value of the arithmetic quotient of itself 

and complex number y. 

WARNING 

a»igiunent operators do not produce a value that can be used in an expression. That is 
the following coitstruction is ^tactically invalid, 
coin)lex X, y, z; 

Jc - ( y +- z ) ; 
whereas, 

X - { y + z ); 

X - { y — 2 ); 
are valid. 

SEE ALSO 

CPLXJNTRCX3C++), cartpol(3C<M'), qplxeiT(3C<H>), cfdxexpOC’M-), and c;dxtiig(3C>M>). 
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(C-M- Complex Math libtaiy) 


CPLXTRIC(3C++) 


NAME 

q>lxtrig - trigonometric and hyperbolic functions for the C-m- complex library 
SYNOPSIS 

#include <complexli> 
class complex { 


public 


); 


friend complex sinfoomplcx); 

friend complex oos(complex); 


friend complex rinh(complex); 

friend complex ooshfcom^lex); 


DESCRIPnON 

The following trigonometric functions are defined for coaplez, where: 

— X and y are of Qrpe conplex. 

y s sin(x) Returns the sine of x. 

y«cosOc) Returns the cosine of X. 

y s sinh(x) Returns foe hyperbolic sine of x. 

y s cosh(x) Returns the hyperbolic cosine of x. 

SEE ALSO 

CPLXJNTRO(3C++), cartpd(3C<t-4-), qfocerKSC'M-), epbeopsOC-M-), and cpbcexp(3C++). 
DUCNOSnCS 

If the inuiginaTy part of z would cause overflow sixth and cosh return (0,0). When the real 
part is large enough to cause overflow, sinh and cosh return (HUGR, HUGE) if the cosine and 
sine of foe iixtaginaty part of x are rKm<4ieg;ative, (HUG^ -HUGE) if the cosine is non>itegative 
and the sine is less tl^ 0, (-HUGE, HUGE) if foe siite is noit>negative attd the cosine is less 
than 0, and (-HUGE, -HUGE) if both sine and cosine are less foan 0. In all foese cases, ermo 
issettoERANGE. 

These errorfoandlir^ procedures may be diax^ed wifo foe function complex_erTor 
(cpb«rr(3C++)). 
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TASiaNTRO(3C++) 


(C-M- Task Libmy) 


TASKJNTRO(3C-m-) 



NAME 

h><k - ccnxnitines, multiple ttueads of control, C<m- task library 

SYNOPSIS 

#include <taskJh> 

class ob|ect; 

class sdied : public ob|ecl; 
class timer : public sdicd; 
class task : public sched; 

class qhead : public object; 
class qtail : public objed; 

class Interrupt^haiidler : public object; 

class histogram; 
class randint; 

class uiand : public randint; 
class erand public randint; 

DESaUFTION 

The C** task libiaiy provides facilities for writing p rogr ams wifo multiple tiueads of control 
witiiin one UNIX ^stm process. Each tiuread of contrd is a task or coroutine. Ea^h task 
is an instance of a user-defined dass derived frxxn dass task, and tiie main program of tiie 
task is tike coikstnictor of its dass. A task can be suspended and resumed without interfer¬ 
ing witik its internal state. Eadi task runs until it explidtiy gives up the processor; there is 
tko p r e-emp t i on. 

Most classes in the task system are derived from tiie base dass object. The base dass 
sched is respondUe for sdieduling and for tiie functionality tiiat is cmnmon to tasks and 
tlmezs. OaK sched is meant to be used strictly as a base dass, that is, it is Illegal to create 
objects of dass sched. Pass task must also be used only as a base dass. The prograiruner 
must derive a dass from dass task, and provide a constructor to serve as tiie task's main 
program. The task system can be used for writing event-driven simulatitms. tasks execute 
in a Emulated time frame. Objects of dass tinier provide a facility for inqdennenting time¬ 
outs and other time-dependent {tiienomena. Classes task, timer, sched, and object and 
their public member functions are described on the taskOC-M-) manual page. 

Classes qhead and qtail enaUe a wide rat^ of message-^assit^ and data^nifferii^ 
sdiemes to be implemented simi^. These classes are described on tiie queueOC-M-) ttumual 
page- 

Class Interrk 9 t_handler provides an interface for writing classes tiiat can %vait for external 
events using UNIX s ystem signals. These classes are described on tiie intenuptOC-M-) manual 

page- 

Class histogram aids data gatiierir^. Cl asses randint, urand, and erand provide ran¬ 
dom number generation. These four cla s s es are described on the tasksitrK3C-4-»-) manual page. 

SEE ALSO 

taskOC-f-f), queue(3C-M-), intesruptOC-i-i-), tasksimOC-M-) 

Stioustrup, B. and Shopiro, J. E., "A Set of C-m- Classes for Co-routine Style Programming,'' in 
AT&T C-M- Language System Release 2X) Ubrary Manuel. 

Shopiro, J. E., "Extending tiie C-m- Task System for Real-Ume Omtrol," in AT&T C-m Language 
System Release 2.0 Library Manual. 
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NAME 

Intemipt_handler - agnal handling for the C-h- task library 

SYNOPSIS 

#inclnde <taskJt> 

class Inteinipt_hatidler : public obfect { 

▼irtaal Toid intenuptO; 

public 

Intetrupt_liandlei(int); 
~Inteinipt_handlciO; 
dbjtypc o.iypcO; “ 

int pendingO; 

); 


DESaUFTION 

Gass Interrupt _h a ndl er allows tusks to wait for external events in the form of UNIX 
S 3 rstem signals. Class Interrupt_handler is derived focmt dass object so diat tasks can 
wait for lnterriq>t _h a n dler objects. Class object is described on die task(3) manual 
page. 

The public member functions sopfriiied in die task ^fstem riaac intern:^_handler are 
listed and described bdow. The following qrmbols are used: 

ih an Zntersupt_bandler object 

i an Int 

CO an obj type enumeration 
Inieirupt_handler ih( i); 

Ccxistmcts a new Intersi^_handler object, ih, which is to wait for a s^nal 
number L (See signaia).) Onoe'm Inteccupt_bandlec object has been estaUished 
for a particular agnal, when that signal occurs, private, virtual i ntemiptO function 
is called at real time. When it returns, contrd will resume at die point where die 
current task was interrupted. That is, s^naJs do not cause the current task to be 
pre-empted. When the currendy running task is su^iended, a ^ledal, built-in 
the mUrrupt derter wiD be sdieduled. This task alerts die Interrupt 
(and any odiers that have received interrupts since die interrupt alerter lasTian), and 
dierd^ makes any tasks waiting for diose Intem^^handlers runnaUe. As 
long as ai^ Interrcpt_handler exists, die scheduler ^ wait for an. interrupt, 
rather than exiting i^ien die run chain becomes empty. 

void intccmptO 

The private, virtual function, Inteirupt_hafidlccsintemtptO is a null function, but 
because it is virtual, the progranuner cm specify die action to be taken at interrupt 
tune by defining an inteimpK) function in a dass derived fiom 
Intern^_handler. 

eo s ih.o_typeO 

Returns the class type of die ol^ (object:: IHTRkHDLER). o_typcO is a virtual 
function. ~ 

i s ih.pendingO 

Returns TRUE except the first time it is called after a signal occurs. 

DIAGNOSTICS 

See task(3). 
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BUGS 

UNIX System V Rdeases 3.1 and 3.2 (SVR3.1 and SVR3.2) for foe Intel 386 madune will not 
call a signal handler wfoen the current task is running on a stadc in foe free store, that is, 
when the current task has a I^ICATED stadc. If you need to use foe ^gn^l handling 
medranisms on foat configuration, you cannot use tasks which have DEDICATED In 

this case, oom;^ the task libraty wifo _SHARED_ONLY defined, which will make SHARED 
the default mode for tasks. (Note: it is insufficient to dedaie all tasks as SHARED 
wifoout coning a _SHARED_<»ILY version of foe task libiaiy, because the internal system 
task, foe mienupt alerter is DEDICAIED by dofewitt ) 

SEE ALSO 

TASICINTRCX3C++), task(3C<H>), queue(3C<M>), tasksiin(3C*M'), signal(2) 

Stroustrup, B. and Shopiro, J. E., "A Set of C++ Oaases for Cb-routine Style Programming,’ in 
AT€^ C++ Language System Rdease 2 j 0 Library ManuaL 

Shopiro, J. E, ’Extending foe C++ Tadc System for Real-Time Control,’ in AT6T C++ Language 
System Rdease 2.0 Library Mamud. 
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NAME 

queue - qheads and qtails for the C^m- task library 

SYNOPSIS 

#iiiclude <taskJi> 


enum qmodetype { EMOD^ 'WMODE, ZMODE }; 


dass qhead : public object { 
public 

qheadfqmodetype «lVMOD^ mt bIOOOO); 
'qheadO; 

qhead* 

cutO; 

object* 

getO; 

objtype 

oJtyptO; 

int 

pendingO; 

void 

pcintfinb int «0); 

int 

puftadefobject*); 

int 

fdcounlO; 

int 

idmaxO; 

qmodetype 

idmodeO; 

void 

selmodefqmode^rpe); 

vtdd 

selmaxtinO; 

vdd 

splicefqtaO*); 

qtail* 

taaO; 


); 


class qtail: public object { 
public 


qtaU* 

qtaUfqmodetype «WMODEr int >10000); 

-qtaUO; 

cutO; 

qhead* 

headO; 

objtype 

ojyp^; 

int 

pendingO; 

void 

pcintfinb int >0); 

int 

putfobject*); 

int 

id^ae^; 

int 

edmaxO; 

qmodetype 

idmodeO; 

void 

splioefqhead*); 

void 

setmodefqmodetype); 

void 

setmaxtint); 


DESCRIPTION 

Classes qbead aitd qtail enaUe a wide range of message-passii^ aitd data-buffering 
sdtemes to be implentented sinq>Iy with ttie C**^ task system. Bodi Ha«sp«; are derived from 
the base <iass object, which is described on the task(3) mamial page. In general, dass 
qhead provides facilities for taking olqects off a queue, and dass qtail provides facilities for 
putting ol^ects on a queue. The objects transmitt^ through a queue must be of dass object 
or of some dass derived from it 
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A queue is a data structure with an associated list of objects in first-in, first-out order. Each 
queue also has associated qhead and qtail Directs attadted (one of each). No public func¬ 
tions are provided to operate on queues directly. Rather all access to a queue is throu^ either 
the attached qhead or fite attached qtail. To create a queue, the programirter iinist declare 
a qhead object aiKi then use fiuit object to call qheadstailO or must dedare a qtail object 
and then use that object to call qtaildheadO. For example: 

qhead qh; 

qtail* qtp *■ qh.tailO; 

Once the queue is established, objects are added to it widi qtailspuK) and objects are 
removed fitnn it with qheadcgetO. 

Objects derived fiom class object have definitions oi when they are ready and pending (not 
ready), qhead objects are ready when the queue is not empty arul pending iWien fire queue 
is ernp^. qtail objects are te^ when tfie queue is not fiiU, and pendir^ when die queue 
isfuU. 

Queues have three attributes: mode, maximum rize, and coanL The size and count attributes 
apply to die queue itsdf, while the mode attribute sqrplies independendy to the and 

^ail of a queue. These attributes are described bdow. 

Both classes qhead and qtail have a mode (set by die constructor) diat contrcds iriiat hq>- 
pens when an object of diat dass is pendiiig. The default is WM(^E (wait mode). I^di 
WMODE, a task that executes qheadsgetO on an enqity queue will be <pifpe«w ied untfl diat 
queue becomes non-enqi^. Similarly, widi WMODE a task that executes qtaih^tO on a 
fiiU queue wfll be su^ien^ until that queue has room for the object to be added to die 
queue In EMODE (error mode), calUng qheadsgetO for an errqrty queue or calling qtailspntO 
for a fiiU queue wUl cause a run time error. In ZMODE (zero mode), if qheadsgetO is ere- 
cuted on an empty queue it wiU return the NULL pointer instead of a pointer to an object In 
ZMODE, if qtailspntO is executed on a fiiU queue, it wfll return 0 instead of 1. The modes of 
a queue's head and tail need not be the same, (lasses qhead and qtail both provide a 
fimction, setmodeO, idiidi wfll reset the mode. 

Queues also have a maximum size, vdiidi is set to 10000 by default Ihat is, die queue can 
hold up to 10000 pointers to objects. It does noL however, (neallocate qiace. The size of a 
queue can be reset with eidier qheadssetmaxO or qtailssetmaxO. 

The count is the nunfoer of objects on a queue 

Both die qhead and qtail constructors optirmally take mode and size arguments. 

The public member functions supplied in the task system qhead and qtail are listed 

and described in the next two sections. The fifllowing symbols are used: 

qh a qhead object 

qt a qtail object 

t a task object 

qhp 

a pointer to a ^lead 
qtp a pointer to a qtail 
op a pointer to an object 
^ a pointer to a task 
L j ints 
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eo an ob jtype enumeration 
eq a qmodetype enumeration 

Class qhead 

Class qhead has one form of constructor, 
qhead qh( eq, |) 

Constructs a qhead object, qh. Both arguments are optional and have default values, 
eq re p re s e nts the mode (see above), which can be WMODE, EMODE, or ZMODE 
WMODE is die default j represents the maximum length of the queue attadied to qh; 
die default is lOCXlO. 

The public m ember functions of class qhead are (in alphabetical order): 
qhp * qhxntO 

Splits qh in two. qheadscatO returns a pointer to a new ^ead, whidi is attached to 
the original queue. Ejects diat are already on die queue and Ejects diat are 
qtailsputO on die original queue, must be retrieved via qhp. qheadacutO modifies qh 
to pcnnt to a new empty queue. A new qtall must be established for qh (writh 
qlijailO ). objects that are qtailr^utO to the new qtall, can be retrieved via a 
qlLgetO. 

Thus, qheadnctttO can be used to insert a filter into an existing queue, without diang- 
ing die appearance of die queue to anyone usng it, and widiout halting the flow of 
objects dirou^ the queue. The filter will int e rcep t objects that are qtailqputO on 
the original qtall when it does a qhcadsgetO on die new qhead. Then the filter 
can qtailsputO objects on the new qtall, where execution of qheadsgetO on die 
original qhead will retrieve them. In other vrords, die filter task uses the neiviy 
established qhead and qtall, while other tasks continue to pntO and getO from 
the original qtall and qhead. qheadsspliceO can be used to restore die queue to its 
original configuration. 

op s qhgetO 

Returns a pointer to the object at die head of die queue, if the queue is not empty. 
If the queue is empty, qheadsgetO 's behavior depends on die mode of qh. In 
WMODE, a task ^t executes qheadsgetO on an empty queue will be suspended 
until diat queue becomes non-empty, vdien the operation can conqriete successfully. 
In EMODE, it will cause a run time error. In ZMODE, it will return the NULL pointer 
instead of a pointer to an object. 

eo s qh.o_type() 

Returns the class type of die olqect (object: :QHEhD). q_typeO is a virtual function, 
i s qhqiendingO 

Returns TRUE if the queue attached to qh is empty, and FALSE odierwise. pendingO 
is a virtual functitm. 

qh.print( i) 

Prints the contents of qh on stdout. It calk the prinlO function for die object base 
class, i ^ledfies die amount of information to be printed. It can be 0, for the 
minimum amount of information, or VERBOSE, for more information. A second 
integer argument is for internal use and defaults to 0. printO is a virtual function. 

i s qh.pud>ack( op ) 

Puts the object denoted by op back on the head of tiie queue attached to qh, and 
returns 1 on success. This allows a qhead to operate as a stadc. A task calling 
qheadsputbackO competes for queue ^>ace with tasks using qtailcputO. Calling 
qheadsputbackO for a full queue causes a run time error in both EMODE and 
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WMODE, and returns NULL in 2MODE. 
i s qhjrdcountO 

Returns the current number of objects in the queue attached to qh. 
i = qhjdniaxO 

Returns the maximum size of the queue attadied to qh. 
eq « qhxdmodeO 

Returns die current mode of qh, WMODE, EMODE, or ZMODE. 
qlusetmode< eq) 

Sets the mode of qh to eq, which can be WMODE, EMODE, or ZMODE. 
qh.setiiiax( i) 

Sets die maxiinum size of die queue attached to qh to i It is legal to decrease the max¬ 
imum bdow the current number of objects on the queue. Doing so means that no 
more objects can be put on the queue until die queue has been drained below the 
new limit 

qluspliccf qtp ) 

Reverses the action of a previous qheadacutO. qheadssplkeO merges the queue 
attadied to qh with die queue attadied to qq». The list of objects on the latter 
queue peoede those on the former queue in die merged list qheadaspliceO deletes 
qh and qtp. qh is meant to be a ^ead diat was previously culO, and qtp is meant to 
be the pointer returned by that cutO. If in merging the queues qheadssplkeO causes 
an empty queue to become non-empty or a fuU queue to become non-full, it will alert 
aU tasks waiting for that state dia^, and add them to the scheduler's run chain. 
(See objectsaleitO on the task(3) manual page.) 

qtp s qh.taQO 

Oeates a qtall objed for the queue attadied to qh (if none exists) and returns a 
pointer, q^, to the new qtail olqect 

Class qtail 

Class qtail has one form of constructor 
qtail qK eq, j ) 

Constructs a qtail obfect, qt Both arguments are optional and have defoult values, 
eq represents the mode (see above), which can be WMODE, EMODE, or ZMODE 
WMODE is die default f represents the maxiinum length of die queue attadied to of 
the defoult is 10000. ^ 

The public member functitms of dass qtail are (in alphabetical c^der): 
qq>« qtcutO 

Splits the queue to which it is applied in two. qtailscutO returns a pointer to a new 
qtail, which is attached to the original queue, objects already on the original 
queue can still be retrieved with a qhead:9et0 to die original qhead. (This is the pri¬ 
mary functional diffdence between qhcadscutO and qtailscutO.) qtailscutO modifies 
qt to point to a new empty queue A new ^ead must be established for qt 
objects that are qtaikqmtO to qt must be retrieved via the new qhead. objects 
that are qtailsputO to q^ will be retrieved via the original ghead 


Thus, qtailscutO can be used to insert a filter into an existing queue, without changing 
the appearance of the queue to anyone using it, and without halting the flow of 
objects dirot^ die queue. The filter will intercept objects that are qtoilsputO on 
the original qtail when it does a qheadsgetO on the new qhead. Then the filter 
can qtailsputO objects on the new qtail, where execution of qheadsgetO on the 
origirud qhead will retrieve them. In other words, the filter task uses the newly 
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estaldished qhead and qtail, while other tasks continue to putO and get() from 
the original qtail and qhead. qtaihspUceO can be used to restore the queue to its 
origiiud configuration. 

qhp - qtheadO 

Creates a qhead object for the queue attached to qt (if none exists) and returns a 
pointer to the new qhead object 

eo « qto_type() 

Returns the class type of Ae object (object::QTAIL). o_type() is a virtual function, 
i s qtpendingO 

Returns TRUE if the queue attadted to qt is full, and FALSE oAerwise. pendingO is a 
virtual function. 

qLprintf i) 

Prints the contents of qt on stdout. It caUs the printO furtction for the object base 
class, i specifies Ae amount of information to be printed. It can be 0, for the 
miitimum amount of information, or VERBOSE, for more information. A secortd 
mteger argument is for mtemal use and defaults to 0. printO is a virtual function. 

i s qLput( op ) 

Adds Ae object denoted by op to the tail of the queue attached to qt, and returns 1 
on success. If Ae queue is fuU, qtailr^utO '» bdtavior depends on the mode of qt In 
WMODE, a task that executes qtailsputO on a full queue will be suspended until 
that queue becomes non-full, when Ae operation can complete successfully. In 
EMODE, it will cause a run time error. In ZMODE, it will return NULL 

i e qtrdspaceO 

Returns the number of objects Aat can be inserted mto the queue attached to qt 
' before it becomes full. 

i s qtrdmaxO 

Returns Ae maximum size of the queue attadied to qt 
eq * qtzdmodeO 

Returns Ae current mode of qt WMODE, EMODE, or ZMODE. 
qL^lice( qhp ) 

Reverses the action of a previous qtailscntO. qtailsspliceO merges the queue attached 
to qt wiA the queue attadied to qhp. The list of objects on the former queue pre¬ 
cede Aose on Ae latter queue m Ae merged list qtailsspliceO ddetes qt and qhp. qt 
is meant to be a qtail that was previously cuiO, and ql^ is meant to be ^ pointer 
returned by that culO. If m merging Ae queues qtailsspliceO causes an enqity queue 
to beomie non-emp^ or a full queue to become iton-fuU, it will alert all tasks wait¬ 
ing for that state dtange, and add Aem to the scheduler's run duan. (See objectsalertO 
on Ae task(3) manual page.) 

qtsetmode( eq) 

Sets the mode of qt to eq, uAidt can be WMODE, EMODE, or ZMODE. 
qtsetmaxf i) 

Sets the maximum size of Ae queue attached to qt to L It b legal to decrease Ae max¬ 
imum bdow the current number of objects on Ae queue Domg so means Aat no 
more objects can be put on the queue until the queue has been drained bdow the 
new limit 


DIAGNOSTICS 

See task(3). 
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SEE ALSO 

TASKJNTRO(3C++), taskOC-M-), inteiTupt(3C-M-), tadtsunOC-M-) 

Stroustnip, B. and Shopiro, J. E., "A Set of C++ Classes for Co-routine Style Programming," in 
AT€/r C++ Longuage System Release 2J) Library Manual. 


June 14,1989 


Page 6 




TASK(3C<m-) 


(C-M- Task libaiy) 


TASIOSC-m-) 


NAME 

task - coroutines, multiple threads of control, C-m- task library 

SYNOPSIS 

#uiclude <taskJi> 


typedef int rPHOMintobject*); 
typedef void (•PFVK); 
ext e r n int _hwm; 

class object { 
public 

enum objtype { OBJECT, TIMER, TASK, (^lEAD, QTAIL, INTHANDLER }; 


}; 


object* 

o_next; 


i^jectO; 


'objcctO; 

void 

ale^; 

void 

fcKgelftaric*); 

virtual objtype o_lypcO; 

virtual int 

pendingO; 

virtual void 

prinKint int *0); 

void 

temembeiftask*); 

static int 

iask_etrof<int object*); 

int 

task_efior(in^; 

static task* 

ttiis_taskO; 

static PFIO 

ctior_fd; 


class sched : public object { 
protected: 

sdiedO; 

public 

enum statetype { IDLEsl, RUNNINGs2, TERMINATEDsi }; 


static task* 

clodc^task; 

void 

canoeKint); 

int 

dont^waitO; 

static long 

getjdockO; 

sdied* 

get^priorityjsdiedO; 

static sched* 

getjtnn_diainO; 

static int 

get_exitjBtatus(); 

int 

ke^_waitingO; 

int 

pendtngQ; 

V<Md 

printfint, int «0); 

statetype 

rdstateO; 

long 

rdtimeO; 

int 

resultO; 

void 

setdodedong); 

static void 

set_exit_status<int); 

virtual void 

setwhofobject*); 

static PFV 

exit fet; 


}; 
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#defiiie DEFAULT_MODE 


DEDICATED 


class task : public sched { 
public 

•num modetype { DEDICATEDsl, SHAREDa2 }; 


protected: 


public 

task(diar* namesO, modefype mode«DEFAULT_MODE, iiU stacksizesSIZE); 

task* 

t_next; 

char* 

t name; 


*bttk(); 

void 

cancelfint); 

virid 

delayfinf); 

static task* 

get_ta$k_diainO; 

objtypc 

o_fypeOr 

int 

preemptO; 

nrid 

print(int int «0); 

▼irid 

lesultisfint); 

void 

sctvduriobjcct*); 

void 

slecpfobject* >0); 

void 

waitfobject*); 

int 

waidisdobject* ~); 

int 

waitvedobject**); 

object* 

who_alerted_mcO; 


}; 


class timer : public sdied { 
public 


tuneiUnt); 

TimcrO; 


o_type(); 

prinMint int sO); 
uoid icseMistO; 

▼(rid sctuduriobject*); 


DESCRIPTION 

A task is an object with an associated program and tfuead of control To use die task sy»- 
tenv dm programmer must derive a dass from dass task, and supf^ a oonstructcm to serve 
as the task's main program. Control in dm task system is based on a concept of operations 
which m^ succeed irrunediatdy or be Uodced, and objects whidi may be ready or pending 
(not ready). When a task executes a Uodcmg operation ca an object diat is ready, the 
operation succeeds immediatdy and die task continues running, but if the object is pend- 
ir^ the task uraits. Omtrol then returns to die sdieduler, whidi diooses die next task 
horn the ready list or nm ctetn. Eventually, the pending object may become ready, and it 
will notify all die tasks diat are waiting for it causir^ die waitir^ tasks to be put on 
the run dmn . 


A task can be in one of three states: 

RUNNING The task is running or it is ready to run. 

IDLE The task is waiting for a pending object. 
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TERMINATED The task has completed its woric. It cannot be resumed, but its result can be 
retrieved. 

The hinctim schedsrdstateO returns the state. These states are enumerations of type sta- 
tetype. These enumerations are in the scope of class sched. 

Most in die task system are derived from class object. Eadi di^erent kind of 

object can have its own way of determining whether it is ready, vdiich irudces it easy to add 
new capabilities to the system. Hovrever, eadi kind of Object can have only one criterion for 
readiness (although it may have several bloddng operations). The criterion for readiness is 
defined by die virtual function pendingO. For all classes derived horn Object, pcndingO 
returns TTIUE if the ^ject is not ready. This invariant should be maintained for user- 
defined derived dasses as wdL 

Each ^ ject contains a list (die rmember ehain) of die teaks that are waiting for it 

When a task atten^>ts an operation on a pending object (that is, it calls a blocking func¬ 
tion), diat teak is put on the rmmber dmn for the object via objecfcaemembciO, and die 
task is suqiended. When the state of an object dianges foom pending to ready, 
objectsaleitO must be called fw the object. (Note, dus is done for dasses in the task sys¬ 
tem. P rogr amm er s udio write classes for whidi tasks can wait, must ensure liiaX 
ob jectsaleilO is called on a state diai^) aleitO diaries die state of all tasks "remembered’' 
the Object from IDLE to RUNNING and puts dim on die sdtedukr's nm dmn. 

The base class, sched, is responsiUe for scheduling and for die functionality that is c omm on 
to tasks and tiaers. Class sched can only be used as a base dass, that is, it is illegal to 
create objects of sched. Class sched also provides facilities for measurii^ simii^ted 
time. A unit of simulated dme can re p rese nt any amount of real time, and it is possiUe to 
compute widiout consuming simulated time. The ^stem dock is initialized to 0 and can be 
set widi sdicdssetdockO once only. Thereafter, only a call to tasksdelayO will cause die dock 
to advance. schedsgetdodcO can be used to read die dodc. 

na<« tlator provides a facility for implementing time-outs and odier time-dependent 
phenomena. A tisaer is similar to a task with a constructor consisting of the singfo state¬ 
ment 

delay *(d); 

That is, %dien a tijaer is created it sing^ waits for the number erf time units given to it as its 
argument, and dien wakes up any tasks waiting for it A timer's state can be eidier RUN¬ 
NING or TERMINATED. 

A task cannot return a value widi die usual function return medianism. Instead, a task 
sets die value erf its result (using taskacsoltisO or taskacanoelQ), at vdiidi time ^ task 
becomes TERMINATED. Then dtis result can be retrieved by eidier tasks via a call to 
sehedsresullO. 

The task constructor takes diree optional arguments: a name, a moele, and a stacksize. The 
name is a dumeter string pointer, vdiich is used to initialize die dass task variable t^naaw. 
This name can be used to provide mexe readaUe eiutput and does riot ad^ the bdiavior of 
the task. 

The mode argument can be DEDICATED (die default vrfien none is specified) or 91ARED, 
(die enumerations of type aodetype in dass task's scope). DENCATED tasks eadi have 
their o«m stack, allocated from die free store. SHARED tasks share stack ^>aoe with the 
task that creates them. When a 91ARED task is running, it occupies the diared stack 
space, while o^es of the active portions of the odier tasks’ stad» occupy save areas. 
SHARED tasks trade ^peed for space: they use less storage than DEDICATED tasks use, 
but task switches among SHARED tasks often involve copying stadcs to and from the save 
area. 
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^ stadssize aiguin^ to tte task constructor r e p resen ts the maximuin space that a task's 
stack can occupy. The default is 750 madiine words. Overflowing the stadc is a fotal error. 

Whm » object of a class derived from class task is created, its constructor becomes a new 
task tet runs m paralld wittt the otfrer tasks fliat have been created. When tfie first task 
IS created, aalnO automatical^ becomes a taskitsdf. 

The public ineniber fonctions siyplied in the task system classes task, object, sched, and 

tlater are listed and described m the next four sections. *n>e following symbols are useA 
t a task object 


o an ^ ject object 
s a sched olqect 
tm a tijaer object 
op a pointer to an Object 


^ a pointer to a task 


sp a pointer to a sched 
^ apcnntertoa 
ir} ints 
1 a long int 


CO an Ob jtype enumeration 


cs a statetype enumeration 


em a aiodetype enumeration 

Class Task 

Class task has one form of constructor, v^iidi is 
task t( cp, em, j) 

Conshuctea task object, t AH fluee arguments are optional and have default values. 

If ^ given, the character string it p oints to is used as ts name, cm represents the 
mode (see above), and can be DEDICATED or SHARED. DEDICATED is W default 
The default mode can be diaiiged to SHARED by recompiling the task library with 

SHAR^(^ drf,j^ See the NOTES seetkS;?^^ the maxiin^^ 

fs stack; ttie default is 750 machine words. 


Most public member functions of dass task are conditional or unconditional reouests for 
suspension. They are (in alfriufoetical order): ^ 

tcanceR 1) 

Puts t into the TERMINATED state, without suspending the calling task (that is 
wiflKMit invokiiig the scheduler), and sets fs result (or "return value”) to L 

tdelayd) 

Subtends t for the time ^mcified by L A ddayed task is in flie RUNNING state, t 
win resume at the current time on the task system efode + L Only a call to delay!) 
causes the dexk to advance. ^ 


tp s task:^et_task_chain() 
tp s Lget_task_chaiii() 

Itetums a pointer to the first task on the list of all tasks (linked by t next 
pointers). ~ 

eo = to_typeO 

Returns Ae class type of t (object: :TASK). o_type() is a virtual function. 
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i s LpreemptO 

Suspends RUNNING task t, makii^ it IDLE. Returns the number of time units left 
in fs delay. Calling preemptO for an IDLE or TERMINATED task causes a runtime 
error. 

tpxintf i) 

Prints the contents of t on stdout. The first argument, i, ^wdfies ttie amount of 
information to be printed. It can be 0, for the mirumum amount of infimnation, VER¬ 
BOSE, for more mformation, CHAIN, for information about eadi object on die chain of 
all tasks, or STACK, for information about the runtime stadc. These argument con¬ 
stants can be ccanlMned with foe or opeator, eg., print (VERBOSE ICHAIH) . A 
sectmd integer argument is for internal use and defoults to 0. priatO is a virtual func¬ 
tion. 

tresaltis( 1) 

Sets the result (or ’’return value”) of t to be the value of i and puts t in foe ’TER¬ 
MINATED state. The result can be examined by calling txesnltO (lesnltO is a member 
function of dass sched). tasks cannot return a value using foe function 
return medunism. A call to taskaesultisO should appear at foe end oi every task 
constructor body (unless foe constructor will execute mfinitdy). A task is pending 
(see sdiedspendir^O ) until it is ’lERMINA’IED. 

Lsetwfoof op ) 

Records foe object denoted by op as foe one that alerted t when it was IDLE. *op is 
meant to be foe object whose state chat^ from pending to ready caused t to be put 
bade on the run dudn. ’This information can be retrieved with taskswfao_alecled_iiMO. 

tsleepf op) 
tsleepO 

Suspends t uncoiviitkmally (puts foe t in foe IDLE state). 'The pp argument is 
optional. If taskssleepO is given a pointer to a peiuiing object as an argumeitt, t 
will be "remembered” by foe deiu)t^ object, so that when foat object becomes 
ready, t vrall be "alerted” and put back on foe nm efiom (via obfecfoalertO ). no argu¬ 
ment is given to taskssleepO, foe event that wfll cause t to be resumed is unspecified. 
Contrast sleepO with waitO, whidi suspends a task conditkmally. taskssleepO does 
not dieck whether foe object denoted by is pendir^. 

twait( op) 

If op points to a pending Object, then t wiU be suspended (put in foe IDLE state) 
until that object is ready. If op points fo an Object foat is not pendmg (that is 
ready), then t will not be suspended at all. Any dass derived fiom <•!«» Object foat 
is ever going be waited for must have rules for when it is pending aivi ready. Each 
object can only have one definition of petKiing. 

i = twaitlistf op ~.) 

Suspettds t to wait for one of a list of objects to beoxne ready. waitlistO takes a list 
of object pointers terminated 1^ a 0 argument If ar^ of foe arguments points to a 
"ready” object, then t will not be suspended at alL waitlistO returns vdien one of 
the objects on the list is ready. It returns foe position in the list of foe object foat 
caused foe return, with positions nutttbered starting from 0. Note foat objects on 
the list other than foe one dettoted by the return value might al<n be ready. 

i s Lwaitveef ) 

Is the same as waitlistO, except that it takes as an argument the address of a vector 
holding a list of object pointers. 
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op * twlio_aleited_ine() 

Returns a pointer to the object whose state change from pending to ready caused t to 
be put bade on the run dudn (put in tf»e RUNNING state). 

_hwin »1; 

Causes the task ^rstem to keep track of tt»e "high water marie" for eadi task's stack- 
that is, the most stack ever used by each task. This infonnation is printed by 
(as kap rinKSTAQO. This mformation is intended [nimarily for debugging purposes, 
and will affect performance ^>eed. _hwm must be set before asty tasks whose hiA 
water marks are of interest are created. Note dutt t%vo tasks are created by a static 
constructor: die internal Interrupt_alerter task and dte "main" task. If you n eed 
accurate infonnation about the high water mark for "main," then hwm must be set by 
a static constructor which is called before diat for the Interruptjdoier task. 

Class Object 

CTass object has one form of ccmstructor 
object o; 

Construct an Object object, o, wdiidi is not on any lists. The constructor fe» kee i» 
ar g um ents. 

Public member functions of dass tfoject are (in alphabetical order): 
o.aleftO 

Changes the state of all tasks "remembered" by o ftom IDLE to RUNNING, puts 

drem (m the scheduler's run cfotR, and removes them from o's rememfor efcom. 

odoiged ^) 

Removes all occurrences of the task denoted by tp horn o's renumber dudn. 
to * o.o_typeO 

Returns the class type of the object o (object: :OBJECT). o typeO is a virtual func¬ 
tion. “ 

i s o.pcndingO 

Returns dte ready status of an object. It returns FALSE if o is ready, and TRUE if it 
is pending. Classes derived from class object must define pendingO if they are to 
be waited for. objectspendingO returns TRUE by default pendingO is a virtual func¬ 
tion. 

o.ptint( i) 

Prmts die contents of o on stdout. It is called by the pcintO funedems for ria«oc 
derived fixwn object. See taskspiintO for a desaiptkm of die arguments.. prinK) is 
a virtual funedon. 

ojememberi ty) 

Adds the task denoted Ity ty to o's remember dudn. Re m e m bered tasks will be 
alerted vdien o's state becomes ready. 

i s objectslask_eixoc( 1, op ) 
i s O.t^_CR0l( L ) 

The central error funedon called Ity task system functions vdien a run dme error 
occurs, i r e pres e nts the error number (see die DIAGNOSTICS section for a list of error 
numbers and dieir meanings), op is meant to be a pointer to the object whidi called 
task_etrot() <»- 0. objectstask_enoiO examines die variable ecror_£ct, and if this 
variable denotes a function, diat funedon will be caUed with i and op as arguments, 
re^jeedvdy. (See error__£ct, below.) Odierwise, i will be given as an argument to 
print_errot(), whidi will print an error message on stderr and call exitti), terminat- 
ii^ the program. The non-stadc, single argument form of task_etxorO is obsolete, but 
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remains for compatibili^. 

^ K objcct=ttus_taskO 
^ m o.this_taskO 

Returns a pointer to the task that is cunendy running. 

PFIO user>defined'-cmir>function; 
ertor_fct« aacr>defined-eixor>laiieti<m 

ein»_lct is a pointer to a funcdcm ttiat returns an Int and takes two arguments: an 
int refnesenting the error number and an object* representii^ the object* dtat 
called task^cixoc. If cnor_lct is set, taskjenoiO will call die ascr*defined<czror> 
function widi die error niutto and the object* as arguments. (Ihe object* 
be 0 if task^ccror was not called by an object.) If aser*defined-ctror<>fancdon does 
not return 0, task_ciioiO will call cxitfi). If die aser«defincd*CRat^fnnction does return 
0, task_eiTOf0 will retry die operation diat caused die error. 

Class Sched 

Both class task and dass timer are derived from class sched. Class ached provides one 
form of constructor, which is prot e ct e d: 

sdieds; 

Constructs a sched dqect, s, initialized to be IDLE and to have a 0 dday. 

Class sched is re^xmsiUe for die funcdonali^ diat is common to tasks and timers. Class 
sched provides the following public member functions: 

sxancelf i) 

Puts s into the TERMINATED state, widiout suspending die caller (diat is, widiout 
invoking the scheduler), and sets the result of s to L 

i - s.dont_waitO 

Returns die number of times keep^waitingO has been called, minus die number of 
times dont_wait0 has been called (excluding die current call). If diese functions are 
used as intended, die return value repre s en ts die number of objects that were wait* 
ing for external events before the current call. See keep_waitiiigO. See interruptOC'M-) 
for a desoiption of how tasks can wait for external events. 

1 s scheifoget^dockO 
1 s s.get_clockO 

Returns the value of the task system dodc. 

i s sdied:;get_cxit_8tatiis0 
i« s.get_exit_statuirf) 

Return die exit status of the task program. When a task program terminates normally 
(diat isy task^error is not called), the program will call exit(i), where i is die value 
passed ty the last caller of sdiedssct_exit_statiisO. 

sp s s.get_prioiity_achedO 

Returns a pointer to a system task, lnternvt_alerter, if a signal that was being 
waited for has occurred. If no interrupt has occurred, get_pziority_sdied() returns 0. 

sp s sdiedsget_nm_diainO 
sp « s.get_tun jdiainO 

Returns a pointer to the run chain, the linked list of ready sched objects (tasks and 
timers). 
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i s sJceep_waitiiigO 

Returns the number of times keep_waitii^) has been called (not counting Ae current 
caU), minus the number of times dont_waitO has been called. kecp_waitiiigO is meant 
to be called when an object that will wait for an external evmt is created. For 
example, it is called %»d»en an Intern^t^handler object is created by the 
lnterrupt_handler constructor (see interrupt(3C++)). The inverse function, 
doiit_waiK), should be called when such an object is ddeted. keep waitmgO causes 
the sdteduler to keep waitii^ (not to exit) when there are no runnable tasks (because 
an external event may make an IDLE task runnaUe). 

i s s.pendingO 

Returns FALSE if s (task or timer) is in ttie TERMINATED state, TRUE otherwise. 
pcndingO is a virtual function. 

S4>rmt( i) 

Flints die contents of s on stdout. It is called by die primO functions for 

derived from sched. See tasksprintf) and timersprintO for a description of die argu¬ 
ments. printO is a virtual function. ^ 

cs s sjdstateO 

Returns the state of s: RUNNING, IDLE, or TERMINATED. 

1 s S.tdtiBM() 

Returns die dock time at whidi s is to run. 
i * sjesuUO 

Returns die result of s (as set taskaesnldsO, taskscancelO, or ) if , 

is not yet TERMINATED, the calling task will be suspended to wait for s to ter¬ 
minate. If a task calls resultO fcv itsdf, it will cause a run tmte error. 

schedssetdockf 1) 
s.setdodc( 1) 

Initializes the system dock to the time given by L Causes a run dme error if used 
more than once. 

schedsset_exit_statns( i) 
s.set_exit_status( i) 

Sets the exit status of die task progrartL When a task {nogiam terminates normally 
(that is, ta$k_error is not called), the program %viU call exidi), where i is the value 
passed by die last caller of set_exit_statnsO. 

s.setwho( op ) 

Is a virtual function defined for tasks and timers; see its definition for those 
The argument is meant to be a pointer to the object that caused s to be a l er ted 
PFV userdefined-exit-fanction; 
exit_fct s nser«dcfined«exit-function 

cxit_fct is a pointer to a function taking no arguments and returning void. If set, the 
task system sdieduler will call the user-defined-exit-function before die program ^ts. 

dock_task « tp; 

Sets tp to be a task diat will be scheduled each time the system dodc advances, 
before any other tasks. The dock_task must be IDLE when it is resumed by the 
scheduler. The dodcjask can suspei^ itself by calling taskssleepO to eisure this. 

Class Timer 

Class timer provides one form of constructor 
timer tm( i); 

Constructs a timer object, tm, and inserts it on the scheduler's run chain. 
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The following public member hmctions are provided for timers: 
eo s tnu>_type() 

Returns the type of foe olqect (object: :TIMER). o_typeO is a virtual function, 
tsuesetf i) 

Resets tm's delay to i This makes repeated use of timers possible. A timer can be 
reset even when it is TERMINATED. 

tni3ctwho( op ) 

Is defined to be null for timers. sctwfooO is a virtual function. 
tmpiinK i) 

Prints foe contents of tan on atdout. The argument is ignored. ptintO is a virtual 
function. 

FILES 

UBDlR/libtaska 

NOTES 

The fade library is suppli ed only for foe following madiines: WE32000-series madimes (eg., 
foe ATAT 3B2), ATAT 3B20, ATAT 6386 WGS, Sun-2 and Sun-3, and foe VAX It must be 
ported to woric on other {^tfonns. 

WARNINGS 

Beware of optimizing compileis foat inline constructors for classes derived from dass tusk! 

Alfoou^ foe task library was engineered to be as free as possiUe from d epert de n des on com- 
lotion ^rstems and dynamic call chains, it does depend on foe existence of stadc frames for 
foe task constructor and constructors for dasses derived from dass task. If foese construc¬ 
tors are irdined by an optimizit^ compiler, unpredictifole behavior vnll result 

For rdated reasons, alfooug^ you must derive a dass from dass task to use foe task library, 
you can only have one level of derivation from dass task. That is, foe s ys tem will iv>t %vork 
rdifoly if you derive a from a dass derived from dass task. 

BUGS 

PE P ICATE P are implemented by building task stacks in foe free store. Because UNIX 
System V Release 2 6VR2) for the WE3200(>4eries maddnes does not allow stadc pointers to 
point into foe free store, DEDICATED tasks carniot be used on foese machines with SVR2. 
In sudt cases, coir^sle foe task library wifo jSHAREDj^iILY defined, whadi will make 
SHARED foe default mode for tasks. (Note it b irmuffident to declare aD tasks as 
SHARED without compiling a j9iARED_C^>lLY version of the task library, because there b an 
internal system task (foe ifdmvpt dertn task, see internet (3C-h>) ) which b DEDI¬ 
CATED by default) 

UNIX System V Rdeases 3.1 and 3.2 (SVR3.1 and SVR3.2) for foe bitd 386 madune will not 
call a sigrud handler when foe current task b running on a stack in foe free store, foat b, 
when foe current task has a DEDICATED stack. If you need to use foe s^;nal handling 
mechanisms (described on foe tasksim(3C-M-) manual p:^ on foat configuration, you cannot 
use which have DEDICATED stacks. In fob case, coirqnle the task fibrary wifo 
SHARED C^JLY defined, which will make SHARED foe default rttcxle for tasks. 

DIAGNOSTICS 

When a task system function encounters a run time error, it caUs objectstask_ecTotO, «vifo one 
of the foIlo%ving error numbers as an argument The table bdow lisb the run time errors the 
task system detects, foe assoebted error messages, aikl explanations of foe errors. 
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Eixor Name 

Message 

Explanation 

1 E_OLINK 

"objectiiddeteO: has chain" 

Attempt to delete an 
object which remembers 
a task. 

2 E_ONEXT 

"objectudeleteO: on chain" 

Attempt to delete an 
object udtidk is still on 
some chain. 

3 E_GETEMPTY 

"qhead:^(): eiiq>^" 

Attenq>t to get bom an 
enq>ty queue in 

E^MODE 

4 E_PUT0BJ 

"qtaihrputO: object on otfier queue" 

Attenqrt to put an object 
already on some queue. 

5 E.PUTFULL 

’qtail:q>ut(): lull” 

Attempt to put to a lull 
queue in E_MODE. 

6 E_BACKOBJ 

"qheachrputbadcO: object on other 
queue” 

Attempt to pmtback an 
object already on some 
queue. 

7 E_BACKFULL 

”qhead::putt)ackO: lull" 

Attempt to pufl>ack to a 
lull queue in E_MODE 

8 EJSETCLOCK 

"sdtecbsetdodcO: cioddsO" 

Qodc was non>zero 
when setdockO was 
called. 

9 E.CLOaODLE 

"schedischeduleO: dock_task not idle" 

The dock_task was not 
IDLE r^dten the dock was 
advanced. 

10 E_RESTERM 

"schedisdiedule: tenninated" 

Attempt to resume a 
TERMINATED task. 

11 E_RESRUN 

"schedisdhedule: running" 

Attempt to resume a 
RUNNING task. 

12E_NEGTIME 

”sched:schedule: clock<0” 

Negative argument to 
ddayO. 

13 E_RESOBJ 

"schedischedule; task or timer on odier 
queue" 

Attempt to resume task 
or timer already on some 
queue. 

14E_HISTO 

"histogranudustogramO: bad arguments" 

Bad arguments for histo¬ 
gram constructor. 

15 E_STAaC 

"tasknrestoreO: stack overflow" 

Task tun time stack 
overflow. 

16 EJSTORE 

"new: Iree store exhausted” 

No more bee store- 
newO buled. 

17E_TASmODE 

"taskdaskO: bad mode” 

Dl^al mode argument 
for task constructor. 

18 EJTASKDEL 

"taslcitaskO: not tenninated" 

Attend to delete a non- 
TERMDMATED task. 

19 E_TASKPRE 

"tasicipreemptO: not running" 

Attempt to preempt a 
rton-RUNNING task. 
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Error Name 

Message 

Explanation 

20 E_TIMERDEL 

"timer::*timei<): not terminated" 

Attempt to delete a iton- 
TERMINATED tinner. 

21 E_SCHTIME 

"schedule: bad tinre" 

Scheduler run chain is 
corrupted: bad time. 

22 E_SCHOBJ 

"sched olqect used directly (iK>t as base)" 

Sched object used 

diiecdy instead of as a 
base class. 

23 E_QDEL 

"queue::*iqueueO: not empty" 

Attempt to delete a non¬ 
empty queue. 

24 E_RESULT 

"taskzresultO: dustask->result()" 

A task attempted to 
obtain its own rKult(). 

25E_WAIT 

"taskrwaiK): wait for selT 

A task attempted to 
waitO for itsdf to TER¬ 
MINATE. 

26 E_FUNCS 

"FiameLajroutnFiameLayoutO: function 

Internal error-caimot 


start" 

determine the call frame 
layout 

27 E_FRAMES 

"PrameLayoufcAameLayoutO: frame 

Internal error-cannot 


size" 

determine foame size. 

28 E_REGMASK 

"task=fudge_retuinO: unerqiected r^gis> 

Intenial error- 


ter mask” 

unerqrected register 

mask. 

29 E_FUDGE_SIZE 

"taslc:fudge_retum(): frame too big" 

Internal error-fudged 

frame too big. 

30 E_NO_HNDLR 

"sigpunc ' no handler for signal" 

No haiuiler for foe geiv 
erated signaL 

31 E_BADSIG 

"illegal signal number" 

Attempt to use a signal 
number that is out of 
range. 

32 E_LOSTHNDLR 

"foterniptjhandler::*lntemipt_handler(): 
sigiud haitdler itot on drain" 



SEE ALSO 

TASICINTRCX3C-M.), mteiruptC3C++), cpieue(3C++), lasksun(3C++) 

Stroustnip, 6. and ^piro, J. £., "A Set of C++ Classes lor Co^utine Programming,* in 
AT€/r C++ Language System Release ZO Ubmry Mamud. 

Shof^, J. E., "Extending the C++ Tadt System lor Real'Ume Qmirol," in ATST C++ Language 
System Release 2X) Library Manual. 

Keenan, S. A., "A Porting Guide for the C++ Coroutine Libiaiy," in AT&T C++ Language Sys¬ 
tem Rekttse 2J0 Library Manual. 
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NAME 

tasksim - histograms and random niunbeis for simiilatfons with facifc 

SYNOPSIS 

tindndc <taskJi> 

class hi s togr a m { 
public 

int 1, t; 

int binsize; 

int nbin; 

bd* h; 

long sum; 

long sqsunt; 

histogramUnt nb int left •<)!, int tiglit «16); 
void addOnt bin); 

▼(dd printO; 

}; 


class landint { 
public 

randintaong seed >4); 
int drawO; 
float fdrawO; 


void scedQong); 

}; 


class uzand : public { 

public 

int low, high; 

urandGnt lo, int hi); 
int drawO; 

}; 


class etand : public randint { 
public 

int mean; 

erandfint m); 
int drawO; 

}; 


DESCRIPTION 

The O*-*- task libraiy can be used to program simulations To suf^rt sudt applications, the 
library supplies classes to ease data gatheriitg and random number gerreratum. 

The public member functions supplied in the task ^stem histo^raa^ randint, 

urand, and erand are listed and described in the next two sections. The following symbcds 
are used; 
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h a histogram ol^ect 
ri a randint olqect 
ur a urand olqect 
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cr a exand object 

i, nb, left tight lo, hi, n 
ints 

1 a long Int 

f a float 


Histograms 

Class histogram provides simple fodlities to generate histogiains. 

Class histogram has (Mie fonn of constructor 
histogram h( nb, left tight); 

Constructs a histogram object, h. A histogram consists of nbin bins, h[0], ... 
h[nbin''l], covering a range Ito r of integers. The optional arguments to ttie his¬ 
togram constructor cone^itd to Ae nund^ of Ians (nbins), and the left (1) and 
right (r) ends of ttte lai^ reqpectivdy. By default, nb is 16, left is 0, and right is 16, 
in other words, there are 16 bins covering a range from 0 to 16. 

iLaddfi) 

Adds one to the ith bin. The sum of die integers added is maintained in aim, and die 
sum of dieir squares is maintained in sqsum. If i is outside the range 1-r, the lai^ 
is extended by eidier decieasii^ 1 or increasii^ r. The nundier of bins however, 
remains constant, so the size of die range covered by a bin is douUed each time the 
size of the rai^ is douUed. 

h.print0 

Prints die numbers of entries for each non-empty bin in h. 

Random Number Generation 

Classes randint, ttraxid,and erand {xovide basic facilities for generatiiig random numbers, 
and can serve as a paradigm for other, a{^dication-q)ecific generators. 

Each olqect of class randint provides an independent sequence of random numbers. 

Class randint has one form of constructor 

randint ri( 1 h 

Cbnstiucts a randint object, zL The argument is optional, and defaults to 0. If 1 is 
g iv en, it is used to seed rL 

i • ridrawO 

Returns an random Int in die range from 0 to UrgestjnsitioeJiiieger. Integers 
letumed by randintsdiawO are uniformly distributed in that rai^ ~ 

f s rlidtawO 

Returns floats diat are unifo rm^ distributed in die interval 0 to 1. 
risee^ 1) 

Reniitializes a generator with the seed L 
Classes urandand erand are both derived frtxn dass randint. 
uzand ni< l<b hi ); 

Constructs a urand object, ur. lo and hi define the rai^ from low to high for the 
distribution of numbers gener at ed by this ol^ect 

i • undzawrO 

Returns a random int in die range low to high. Integers returned from 
uxandsdzawO will be uniformly distributed in die range. 

erand erf i) 

Constructs an erand ol^ect, er, ivith i as the mean for the distribution of random 
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numbers generated. 


i s eruiiawO 


Returns a random Int. Integers returned from etandsdxawO will be exponentially 
distributed around the mean. ciandsdrawO uses logO from the C math library, so 
programs using it must be loaded with -In. 


DIAGNOSTICS 

See task(3). 

SEE ALSO 

TASKJNTRO(3C<m-), task(3C-M-), intem^3C-M>), queueOC^H-) 

Stroustrup, B. atal Stopiro, J. Ev ”A Set of C'M' Classes for Conxmtine Style Programming,’' in 
AT&T C** Language System Rdease 2J0 Library Manual 
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NAME 

iostream - bufterin^ formatting and input/oatput 
SYNCH^IS 

mduie <iostreamJi> 
dass strcaabnf ; 
dass ios ; 

dass istream : virtoal poUk ias ; 
dass ostrean : dmial pobik ins ; 

dass ostrcaaT wiffaas^ : paUk odw am ; 
dass iostre a u ^ w ilhtssitB : pobfic indrraa i ; 




extera ktreaB^widiassigB dm ; 
cxtera ostreanjdthassigB ant ; 
eztera ostrcam_withassigB ccrr ; 
extern ostreanjwithassi^ dog ; 


iiadode distreanJi> 
dass ilebof : pnbBc streanbof ; 
dass fttrean : pobBc iostrcan ; 
dass ifs tre a n : pobBc istrean ; 
dass oCstrean : pabBc ostrean ; 

fiadade <strstreamJi> 
dass strstreambaT : pobik streanbof ; 
dass istrstrean : pobik istrean ; 
dass ostr s tre an : pobik ostre a n ; 

fiodode <stdiostreamJi> 

dass stdiobof : piAik streanbof ; 

dass stdiostrean : pifolk ks ; 

DEsaupnoN 

The C'H> iostream padage declared in iostreaa.h and ofoer header files consists primarily 
of a collection of classes. Alfitougb originally intended only to si^rport ii^t/ou^t, the 
padu^ now suppcots rdated activities such as incore formattii^. Tl^ package is a mostly 
source-con^tible extension of foe earlier stream I/O package, desorbed in The C-h- Program¬ 
ming Lmgtiatge by Bjame Strbustn^. 

In the iostream man pages, duxructer r e fe r s to a value that can be hdd in either a char or 
unsigned char. When functions foat return an int are said to return a duuacter, they 
return a positive value. Usually such functions can also return EOF (>1) as an error indication. 
The piece of memory foat can hold a character is referred to as a byte. Thus, eifoer a char* 
or an unsigned char* can point to an array of bytes. 

The iostream padcage consists of several core classes, idiich provide the base functioiudi^ for 
I/O conversion aikl bufierii^ and several ^redalized das^ derived from the core 
Both groups of classes are listed below. 

Core Classes 

The core of the iostream package comprises the following classes: 
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streanbuf 

This is the base dass for buffers. It supports insertion (also known as storing 
or putting) and extraction (also known as fetching or getting) of characters. 
Most members are inlined for efficiency. The public interface of dass stcean- 
buf is described in dmf.pub(3C-*-*-) and the protected interface (for derived 
classes) is described in s^^tOC-*-*-). 

ios This dass contains state vaiiaUes that are common to the various stream 
dasses, for exan^, error states and formatting states. See ws(3C**). 

1stream 

This dass supports formatted arwl unformatted conversion from sequences of 
dtaiacters fetdted from streaabufs. See istreim^3C**). 

ostreaa 

This cl a s s supports formatted arul unformated conversion to sequences of char¬ 
acters stored into stceanbufs. See ostream(3C*+). 

lostream 

This dass comtanes Istream and ostream. It is intended for situations in 
whidi bidirectional operations (irtserting into and extractmg horn a single 
sequence of diaracters) are desired. See^3C<M>). 

Istream^wlthasslgn 

ostreamjirlthasslgn 

lostreamjirlthasslgn 

These cl ass es add assigrurrent operators and a construcfor %vid) no operands to 
foe correspoitding cl a s s mthout assignment. The jeedefined streams (s ee below) 
cln, cout, cere, and clog, are objects of foese classes. See istream(3C*+), 
ostream(3C’h*), artd ws(3C++). 

lostream^lnlt 

This dass is present for technical reasons rdatmg to initialization. It has no 
public members. The loatream^lnlt constructor mitializes foe predefined 
streams (listed bdow). Because ol^ect of this is declared in the 
fostreainJi header file, foe constructor is called once each Hme the is 

induded (although foe real initialization is only done once), aiul therefore the 
inedefined streams will be initialized before foey are used. In some cases, glo¬ 
bal constructors may need to call foe lostreamjrtit constructor eq>lidtly to 
ensure foe standard streams are iiutialized before'foey are used. 

Predefined streams 

The foUowir^ streams are predefined: 

cln The staiulard input (file descriptor 0). 

cout The standard output (file descriptor 1). 

cere Standard error (file desoiptor 2). Output throu^ fois stream is unit-buffered, 
which means fiiat characters are flushed after eadi inserter operation. (See 
ostreamsosfxO in ostream(3C**) attd los:: unltbuf in ios(3C+*).) 

clog This stream is also directed to file descriptor 2, but unlike cecr its output is 
buffered. 

cln, cere aitd clog are tied to cout so fltat any use of these will cause cout to be 
flushed. 

In addition to foe core dasses enunnerated above, the iostieam package contains additional 
dasses derived from them atKl dedared in ofoo* headers. Programmers iiuiy use these, or may 
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dioose to define their own classes derived from the core iostream classes. 

Classes derived from streanbuf 

Classes derived from streanbuf define the details of how characters are produced or con¬ 
sumed. Derivation of a class from streanbuf (the protected interface) is discussed in 
sbuf.prot{3C-*"*-). The available buffer classes are: 

filebuf 

This buffer class supports I/O through file descriptors. Members support 
openit^ closing, and seddng. Conunon uses do not require the program to 
manipulate file descriptors. See fiUbufOC*-*-). 

stdiobuf 

This buffer class supports I/O duou^ stdio FILE structs. It is intended for 
use when mixing C and C<t-9> code. New code should prefer to use f ilebufs. 
See stdiobufOC-*^). 

Strstreanbuf 

This buffd’ class stores and fetdtes characters from arrays of bytes in memory 
(i.e., strings). See ssbuf(3C++). 

Classes derived from istrean, ostreanv and iostrean 

Classes derived from Istreanw ostrean, and iostrean specialize the core classes for use 
wid> particular kinds of streanbufs. These classes are: 


ifstrean 

ofstrean 

fstrean 

These classes support formatted I/O to and from files. They use a filebuf 
to do the I/O. Common operations (such as openiitg and closing) can be done 
directly on streams without explicit mention of filebufs. See fotreamOC-*-*-). 


istrstrean 

ostrstrean 

These classes support "in core” formatting. They use a strstreanbuf. See 
stTStream(3C++). 

stdiostrean 

This class specializes iostrean for stdio FILES. See stdiostreamJi. 


CAVEATS 

Parts of the streanbuf dass of the old stream package that should have been private were 
public. Most iK>nnal usage will compile properly, but any code that depends on details, 
including classes that were derived from streanbufs %vill have to be rewritten. 

Performance of programs that copy from cin to cout may sometimes be improved by break¬ 
ing the tie between cin and cout aitd doing explicit fluste of cout. 

The header file strean. b exists for compatibility wiA the eaiiier stream package. It indudes 
iostrean.h, stdio.h, and some oth^ headers, and it declares some obsolete functions, 
enumerations and variables. Soirte members of streanbuf and ios (not discussed in these 
ii\an pages) are present only for backward compatibility with the streaun package. 

SEE ALSO 

ios(3C++), sbuf.pub(3C++), sbuf.prot(3C++), filebuf(3C++), stdiobufOC-M-), ssbuf(3C++), 
istream(3C+-»-), ostream(3C++), fetream(3C++), strstream(3C-M-), manip(3C-«-«-) 
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NAME 

- buffer for file I/O. 

SYNOPSIS 

Boiditde <ia5treamJi> 

lypedcf kNig streaoiofT, streampos; 

dass ios { 

public 

cDum aeckjdir { beg, cur, cad ); 

cauB «pca_Bode { ia, out, ale, app, tmac, aocreate, aoreplace } ; 

// and lots of oOier ^tff, set iosOC**) 

} ; 

fiadade ^rtreaai.h> 

dass filebaf : public streaaibuf { 
public 


Static const 

int openprot ; f* default protection for open */ 

fiebufO ; 
filebaJ(int d); 

fiiebnf(int d, char* p, int len) ; 

filebaf* 

attach(int d) ; 

filebaf* 

doseO; 

hit 

fdO: 

int 

bjopenO; 

filebaf* 

open(char *iianie, int omode, int protsopcnprot) ; 

streampos 

seekoflXstreaiDofr, seekjdir, int omode) ; 

strcampos 

seekposfstreampos, hit omode) ; 

strcambuf* 

setb^char* p, int len) ; 

int 

bjkO ; 


}; 

DESCRlPnON 

fllebufs specialize streaaibufs to use a file as source or sink of characters. Characters are 
consumed by doing writes to the file, and are produced by doing reads. When the file is seek- 
able, a filebuf allows sedcs. At least 4 diaracters of putt>ack are guaranteed. When foe file 
permits reading and writing, the filebuf permits bofo storing and fetching. No special 
action is required between gets and puts (unlite sbiio). A filebuf that is connected to a file 
descriptor is said to be open. Rles are opened by default with a protection mode of open- 
pcot, which is 0644. 

The resewe arm (or bu^, see sbt^.ptd>(3C**) and sbt^4frot(3C++)) is allocated automatically if 
one b not spedfied explidtly with a constructor or a to sefoufO. filebufs can also be 
made unbu^ed with certain atgumenb to the constructor or setbufO, in which case a ^tem 
call is made for each character that b read or written. The gel and put pointers into the reserve 
area are conceptually tied together; foey bdiave as a single pointer. Therefore, the descriptions 
below refer to a sin^e get/put pointer. 

In the descriptions below, assiime: 

— f is a filebuf. 

— pfb b a filebuf*. 

— psb is a streaaibuf*. 

— i, d, len, and prot are ints. 
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— name and ptr are charts. 

— mode is an int representing an open_a»de. 

— off is a streamof f. 

— p and pos are streajnpos's. 

— dir is a se«lc_dir. 

Constructors: 

fiiebnfO 

Constructs an initially dosed filebuf 
fflebaAd) 

Constructs a filebuf connected to file descriptor d. 
filebuftd, p, len) 

Constructs a filebuf connected to file descriptor d and initialized to use tbe reserve 

^ ste^ at p ^^taining kn bytes. If p is nuU or len is zero or less, the 
filebuf will be unbuffered. 

Members: 


pfbsfottachfd) 

Connects f to an open file descriptor, d. 
is already open. 


attadiO normally returns &f, but returns 0 if f 


pfb«f.doseO 

Flushes any luting output, closes the file descriptor, and disconnects f. Unless an 
error occurs fs error state will be cleared. doseO returns &f unless errors occur, in 

dlSS ^ ^ descriptor and f 


i=fid() Returns i, the file descriptor f is connected to. If f is dosed, i is EOF. 
isfJs_openO 

Returns non-zero when f is connected to a file descriptor, and zero otherwise. 
pfbsf.open(iume, mode, prot) 

^ protection mode prot unless ios: :nocreate is specified in 

mode. By default p^ is filebuf: :openprot, which is 0644. Failure occurs if f is 
alrea^op^ openO normally returns &f, but if an error occurs it returns 0. The 
rnonbers of open.mode are bits that may be or'ed together. (Because the or'ine 

than an ^n mode argument.) Til 
meanings of these bits m mode are described in detafl in ^traon(3C++). * 

p=£seekoff(oft dir, mode) 

Moi^^ g^put pointer as designated by off and dir. It may fail if the file that f is 
atta^ to does not support seeking, or if the attempted motion is otherwise invalid 
(such as attempting to seek to a position before the beginning of file), off is inter- 
preted « a aunt ^tive to the place in the file specified by dir as described in 
^/.p««3C++). mode is ignored. seekoffO returns p, the new position, or EOF if a 
failure occurs. The position of the file after a failure is undefined. 

psf.seekpos(pos, mode) 

Moves ^ file to a position pos as described in sbuf.pub(3C++). mode is ignored. 

seekposO normally returns pos, but on failure it returns EOF. 


psbsf.setbuf(ptr, len) 

Sets up the reserve area as len bytes beginning at ptr. If ptr is null or len is less than 
or equal to 0, f will be unbuffered. setbufO normally returns &f. However if f is 
open and a buffer has been allocated, no changes are made to the reserve area or to 
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the buffering status, and setbufO returns 0. 
i=f.sjmc() 

Attempts to force the state of the get/put pointer of f to agree Gx synchronized) with 
the state of the file fJdO. This means it may write characters to the file if some have 
been buffered for ou^t or atten^t to reposition (seek) the file if characters have been 
read aird buffered for input Normally, s^cO returns 0, but it returns EOF if syn- 
drroiuzation is itot possible 

Sometiines it is necessary to guarantee that certain characters are vmtten togefiter. To 
do this, the program should use sefirafO (or a constructor) to guarantee that the 
reserve area is at least as large as the number of characters foat must be written 
together. It can then call S3nic0, then store die characters, then call syncO again. 

CAVEATS 

attachO aird the constructors should test if the file descriptor they are given is open, but I can't 
figure out a portable way to do that 

There is no way to force atomic reads. 

The UNIX system does not usually report failures of seek (e.g. on a tty), so a filebuf does rtot 
either. 

SEE ALSO 

sbuf.pub(3C++), sbuf.prot(3C++), fotreamOC-M-) 
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NAME 

fstream - iostream and streambuf spedaliTed to files 
SYNOPSIS 

#iDdude <fstreain.h> 

typedef long streaoofT, streampos; 
class ios { 


public 

enum 

ecum 

seek_dir { beg, cur, end } ; 

open_aiode { in, out, ate, app, trunc, nocreate, norepiace } ; 


enum io_state { goodbit=4), eofbit, failbit, badbit } ; 

// and lots of other stuff, see ios(3C++) ... 

} ; 


class ifstream : istream { 

i&treamO ; 

i&treamfchar* name, int =ios::in, int prot =filebuf::openprot) ; 

i&tream(int fd) ; 

ilistream(int fd, char* p, int 1) ; 

void 

void 

void 

filebuf* 

void 

}; 

attach(int fd) ; 
closeO ; 

openfchar* name, int sios::in, int prot=filebuf::openprot) ; 
rdbufO ; 

setbnf(ciiar* p, int 1) ; 

dass ofstream : ostream { 

ofstreamO ; 

ofstream(cbar* name, int =ios::out, int prot =filebuf::openprot) 

ofstream(int fd) ; 

ofstream(int fd, char* p, int i) ; 

void 

void 

void 

Olebuf* 

void 

}; 

attach(int fd) ; 
doseO ; 

open(char* name, int =ios::out, int prot=filebuf::openprot) ; 
rdbufO ; 

setbufjchar* p, int i) ; 

class fstream : iostream { 

fstreamO ; 

fstreamfchar* name, int mode, int prot =filebuf::openprot) ; 

fstream(int fd) ; 

fstream(int fd, char* p, int 1) ; 

void 

void 

void 

filebuf* 

void 

attach(int fd) ; 
doseO ; 

open(char* name, int mode, int prot=fiiebuf::openprot) ; 
rdbufO ; 

setbttf(cbar* p, int 1) ; 
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DESCRIPTION 

ifstreain, ofstrean, and fstream specialize istreain, ostream, and iostream, 
respectively, to files. That is, the associated streambuf will be a f ilebuf. 

In the following descriptions, assume 

— f is any of ifstreaxn, ofstrean, or fstrean. 

— pfb is a filebuf*. 

I — psb is a streanbuf 

— name and ptr are char*s. 

— i, fd, len, and ptot are ints. 

— mode is an int representing an openjnode. 

Constructors 

The constructors for zstrean, where x is eitfter if, of or f, are: 
zstreamO 

Constructs an unopened xstream. 
xstreamfname, mode, prot) 

Constructs an xstream aitd opens file name using mode as the open mode 
arid prot as the protection mode. By default, prot is filebuf: lopenprot, 
which is 0644. The error state (lo_state) of the constructed xstream will 
indicate failure in case die open failsT 

xstream(d) 

Ccmstnicts an xstream coimected to file descriptor d, which must be already 
open. 

xstTeam(d,ptr,len) 

Constructs an xstream connected to file descriptor fd, and, in addition, initial¬ 
izes the asso ci ated filebuf to use the len bytes at ptr as the reserve area. If 
ptr is null or len is 0, the filebuf will be unbuffered. 

Member functions 

lattachfd) 

Connects f to the file descriptor d. A failure occurs when f is already con¬ 
nected to a file. A failure sets ios:: failbit in fs error state. 

IdoseO 

Qoses any associated filebuf and thereby breaks the connection of the f to 
a file, fs error state is cleared except on foilure. A failure occiu^ when the call 
to fjrdbuf()->close() faQs. 

f.open(name,mode,prot) 

Opens file name and connects f to it If die file does ruit already exist, an 
attempt is made to oeate it with protection mode prot unless 
ios:: noccaate is set. By default, prot is filebuf:: openprot, whidt is 
0644. Failure occurs if f is already open, or the call to fxdbufO->openO fails. 
ios::failbit b set in f's error status on failure. The members of 
openjnode are bits that may be or'ed together. (Because the or'ing returns an 
int, openO takes an int radter than an openjnode argument) The 
meanings of diese bits in mode are 

ios::app 

A sedc to the end of file is performed. Subsequent data written to the 
file is always added (appended) at the end of file. On some ^sterns 
this is implemented in the operating system. In others it is imple¬ 
mented by seeking to the end of the file before eadi write, ios:: app 
implies ios::out. 
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ios::ate 

A seek to the end of the file is performed during the openO. 
los:: ate does not ios:: out. 

los::in 

The file is opetted for ii^t ios:: in is implied by construction and 
opens of if streaas. fstreams it indicates that input operations 

should be allowed if possiUe. Is is l^al to irKdude ios::in in the 
nnodes of an ostream in which case it in^lies that the origirud file (if 
it exists) should not be truncated. 

ios::out 

The file is opened for output ios: :out is iii^>Iied by construction 
aial opens of ofstreans. For fstream it says that output opera¬ 
tions are to be allowed, ios: :out may be ^redfied even if prot 
does not permit output 

ios::trunc 

If ttie file already exists, its contents will be truncated (discarded). Ihis 
mode is iizq>lied adten ios::out is specified (induding in 4 >licit 
^redfication far ofstream) and neidier ios: :ate nor ios: :a^p is 
^tedfied. 

ios::nocreate 

If die file does not already exist the openO will faU. 
ios::noreplace 

If the file already exists, die openO will fail. 

pfbsfjdbufO 

Returns a pointer to die filebuf associated with f. fstceamsrdbnfO has the 
same meanir^ as iostceamsrdbnfO but is typed differendy. 

psbs£.sedmf(p4en) 

Has die usual effect of a sedrafO (see fUdn^SC**)), offering space for a reserve 
area or requesdr^ unbuffered I/O. Normally die returned psb is txdbufO, 
but it is 0 on failure. A failure occurs if f is open or the call to ItdbufO- 
>sefimf fails. 


SEE ALSO 

fikbufOC-M-), istreamOC'M-), ios(3C*M-), ostreamOC'M-), sbuf.pub(3C'H>) 
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NAME 


ios - input/output formatting 


SYNOPSIS 

•indude <iostreamJi> 


dass ios { 
public 


iojdate { foodbitsO, eolbit, fidlbit, badbit }; 
open^mo^ { in, out, ate, app, tnmc, nocreate, noreplace }; 
seekjdir { b^, cur, end }; 

/* flags for coutrolliBg foraud */ 
ennm { skipussOl, 

left=02, rightaOd, interaal=010, 
deca020, odsOdO, hexaOlOO, 

iho wb a5e-4 )200, sfeowpointsOdOO, iippercase=01000, slMmpos=02000, 
scientific=04000, fizedaOlOOOO, 
nnitbnfa020000, stdio=040000 }; 
static const long basefidd; 

I* dec|oct|hez */ 
static const long a^jnsifidd; 

/* left|ri|^|intanal */ 
static const long 


public 


int 

/* sdentificl fixed */ 

iosfstreanibiif*); 

badO; 

static long 

bitallocO; 

void 

dearfint state =0); 

int 

eolO; 

int 

idIO; 

char 

fiDO; 

diar 

filKcbar); 

long 

flagsO; 

long 

flagsOoag); 

int 

goodO; 

long& 

hvordGnt); 

int 

operatoriO; 

int 

operator void*0; 
prcdsionO; 

int 

predskmOnt); 

streambnf* 

rdbnfO; 

void* & 

pnordQnt); 

int 

rdstaleO; 

long 

setf(long setbHs, long field); 

long 

setfjlong); 

static void 

Sjmc with stdioO; 

ostream* 

tieO;” 

ostream* 

tiefostream*); 

long 

unsetfOong); 

int 

widthO; 

int 

widthOnt); 

static int 

xallocO; 
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protected: 


iosO; 

initCstreambuf*); 


private: 


void 


ios(ios&); 

operators(ios&); 


}; 


ostreamic 

ostreain& 

ostreain& 

istreain& 


ios& 

ios& 

ios4c 


/* Manipulators V 
dec(ios&); 
hex(ios&) ; 
oct(ios&) ; 
endKostreamjc i) ; 
endsCostreamtc i) ; 
flush(ostreain&); 
ws(istream&); 


DESCRIPTION 


■n»e str^ cl a s s es derived ftom class ios provide a hi^ levd interlace that supports 
transferring fonnatted and unformatted information into and out of streaabufs. This 
manual page describes the operations ootmnon to both input and wit p tit 

Several enumerations are dedared in dass ioa, open node, io_state, seek_dir, and 
format flags, to avwd poUutir^ flie gfobal name qiace. The io states are described on this 
manual page under ’Error States." The format Adds are also described on this p» g». under 
"Formatting." The openjaodes are described in detail in fstream(3C*+) under openO. The 
seekjdlrs are described in sfotfpuM3C*M-> under seekoffO. 

In the Idlowir^ descriptions assume: 

— sarui$2are ioss. 

— srisan ios£. 

— sp is a ios*. 

— i, oi j, and n are ints. 

— If, and b are longs. 

— cattdocare chars. 

— osp arvi oosp are ostrean*s. 

— sb is a streanbuf*. 

— pos is a streaaipos. 

— off is a streanoff. 

— dir is a seek_dlr. 

— mode is an int repres e n ting an open_Bode. 

— fct is a furtction with type lose (*) (lose). 

— vpisa void*fi. 

Constructors and assigrunent; 

iostsb) The strea n bu f denoted by sb becomes the streanbuf as*fw*iatgfl with the 
constructed ios. If sb is null, flte effect is undefined. 


ios(sr) 

s2«s 


O^iyit^ of ioss is not wdl-defined in geiteral, flterefore the constructor and 
assigrunent operators are private so that the con^iler will conq}lain about 
attempts to copy ios objects. Copyir^ pointers to iostreans is usually 
what is desired. 


iosO 
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initCsb) 

Because <•!*« ios is now inherited as a virtual base dass, a constructor with no 
arguments must be used. This constructor is dedared protected. Therefore 
iosdniKstieaihbuf*) is dedared protected and must be us^ for initialization of 
derived classes. 


Error States 

An ios has an internal error state (whidi is a collection of the bits dedared as io__states). 
Members rdated to tihe errOT state are: 

i«s.zdstateO 

Returns die current error state. 
s.dear<i) 

Stores i as the error state. If i is zero, dus dears all Ints. To set a bit without 
dearir^ previously set bits requires somediing like 
Sideai<ios:^adbit| sjdstateO). 

i«&goodO 

Returns non*zero if the error state has no bits set, zero otherwise. 
iss^eofO 

Returns non-zero if oofbit is set in the error state, zero otherwise. Normally 
diis bit is set sdien an end-of-file has been encountered during an extractioru 

iss^O 

Returns non-zero if eidier badblt or failbit is set in the error state, zero 
odierwise. Normally this indicates diat some extraction or conversion has 
failed, but die stream is sdll usable. That is, once the failbit is deared, I/O 
on $ can usually continue. 

ia&badO 

Returns non-zero if badbit is set in die error state, zero otherwise. This usu¬ 
ally that some operation on sjrdbufO has failed, a severe error, from 

whidi recovery is probaNy iirqxissiNe. That is, it will pirobably be imposable 
to continue I/O operadteis on s. 

Operators 

Two operators are defined to allow convenient checking of the error state of an ios: opeta- 
toriO and operator void*0. The latter converts an ios to a pcmter so that it can be compared 
to zero. The conversion vrill return 0 if failbit or badbit is set in the error state, and will 
return a pointer value odierwise This pointer is not meant to be used. This allows one to 
«vrite ex p ressions such as: 

if (dn),. 

if ( dn » X ) .. 

The ! operator returns non-zero if failbit or badbit is set in the error state, which allows 
expressions like the foUowir^ to be used: 

if (Scout) ^ 


Formatting 

An ios has a format state that is used by input and output operations to control the details of 
formatting operations. For other operations the format state has no particular effect and its 
components may be set and examined arbitrarily by user code. Most formatting details are 
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oontroUed by using Ae setfC), and unsetfO functions to set the following flags, whidt 

are dedared in an enumeration in dass ios. Three odier components of the format state are 
oontrdled separatdy with the functions fiUO, widtfaO, and predsionO. 

skipws 

If skipws is set, white^sace will be ski|^)ed on input This af^lies to «-aiar 
extractions. When skipws is not set, wdiitespaoe is not skipped before the 
extractor b^ins oonveRion. As a {wecaution against looping, zero width fields 
are considered a bad format by die e x trac tors , so if the next diaracter is whi¬ 
tespace and the skip vaiiaUe is not set, die aiidunetic extractors will signal an 
error. 


left 

ci^t 

internal 

These control die padding of a value. When left is set, the value is 
left-adjusted, diat is, the fill character is added after the value. When right 
is set, die value is right-adjusted, diat is, the fill diaracter is added before the 
value When internal is set, die fill diaracter is added after any leading 
sign or base indication, but befmie die value Right-adjustment is the defoult if 
none of diese flags is set These fidds are coUectivdy identified by the static 
member, ios: :ad)ustfield. The fill diaracter is contrdled by the fiUO 
function, and die ividdi of padding is conboUed by the widthO function. 


dec 

oct 

hex 

These flags control die conversion base of a value Ihe conversion base is 10 
(dedmal) if dec is set but if oct or hex is set, ccmversions are done in octal 
or hexidedmal, respective^. If none of these is set insertions are in dedmal, 
but extractions are i n terpreted according to die lexical conventions for 
integral constants. These fidds are ooUecdvdy identified by the static member, 
ios: :basefield. The manipulates her, dec, and oct can also be used to 
set die ceiversion base, see "Built-in Manipulators’ bdow. 

showbase 

If shoiAase is set insertions will be converted to an external form diat can 
be read according to die lexical conventions for integral constants, 
showbase is unset by default 

showpos 

If showpos is set, dien a "4-” «rill be inserted into a decimal conversion of a 
postive int^ral value 

uppercase 

If uppercase is set dien an uppercase "X" will be used for hexadecimal 
conversion when showbase is s^ or an uppercase "E" will be used to print 
floating point numbers in scientific notation. 

shoifpoint 

If showpolnt is set trailing zeros and dedmal points appear in the result of a 
floating point conversion. 

scientific 

fixed 

These flags control die format to which a floating point value is converted for 
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insertion into a stream. If scientific is set, the value is converted using 
scientific notation, where there is one digit before the decimal point and the 
number of digits after it is equal to tf»e precision (see below), whidi is six by 
defoult An uppercase "E" will introduce the oqwnent if uppercase is set, a 
lowercase "e" will appear otherwise. If fixed is set, ti»e value is converted to 
decimal notation with precision digits after the decimal point, or six default. 
If neither scientific nor fixed is set, then dte value will be converted 
using either notation, dq>ending on the value: scientific notation wQl be 
only if the exponent renting fiom tfie conversion is less fiuit -4 or greater 
than die predaon. If Showpoint is not set, trailing zeroes are removed from 
the result and a dedmal point ^jpeais only if it is followed ly a digit 
scientific and fixed are coQectivdy identified by the static member, 
ios:: f loatf ield. 

unitbuf 

When set, a flush is perfcxmed by ostzeamsosficO after eadi insertion. Unit 
buffering provides a oonq)fDmise between buffered ouqnit and unbufiered out¬ 
put Performance is better under unit buflering than unbuffered output vdtich 
makes a system call for each character output Unit bufiering makes a ^tem 
call for each insertion operation, and doesn't require the user to call 
ostreamsflushO. 

stdio When set, stdout and stderr are flushed by ostreamsosfxO after each 
insertion. 

The following functions use and set the format flags and variables. 
ocss^(c) 

Sets the "fill diaracter" format state variable to c and returns the previous 
value, c will be used as the padding character, if one is necessary (see widttiO, 
bdow). The default fin or padding (haracter is a space. The positioning of the 
fiU dtaracter is determined by the right, left, internal flags, see above. 
A parameterized manipulator, setfiU is also availaUe for setting the fiU diarac- 
ter, see mamp(3C**). 

c^smo 

Returns flie *fiU character” format state variable. 
las.fiagsO 

Returns foe current format flags. 

Issflagsff) 

Resets aU foe format flags to fltose specified in f and returns the previous set¬ 
tings. 

oiss.precisioa(i) 

Sets tfie "precision” format state variable to i and returns the previous value. 
This variable controls flie number of significant digits inserted the fl o at i ng 
point inserter. The default is 6. A paratiteterized manipulator, setprecision is 
also available for setting the predaon, see mtnip(3C-M-). 

iss.precisionO 

Returns foe "precision” format state variable. 
l=s.setf(b) 

Turns on in s foe format flags marked in b and returns foe previous settings. 
A parameterized manipulator, setiosflags performs foe same function, see 
mardpOC-*-*-). 
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lss^etf(b^ 

Resets in s only the format flags specified by f to the settings marked in b, and 
returns the previous settings. That is, tihe format flags specified by f are 
cleared in s, then reset to be those ntarked in b. For example, to change the 
conversion base in s to be hex, one could write: s.setf(ios:diex,iosnbasefield) 
ios: :base£ield specifies the conversion base bits as candidates for drange, 
aird los:: hex ^^edfies the new value. s.setf(04) wiU clear all the bits 
specified by f, as will a parameterized rrranipulator, resetiosfiags, see 
infln^3C++l. 

lss.nasetf(b) 

Unsets in s the Ints set in b and returns the previous settings. 
oiss.wid&G) 

Sets foe "fidd width" format variable to i aird returns foe previous value. 
When foe fidd width is zero (foe default), inserters will irtsert only ^ many 
dtaracters as necessary to represent foe value being inserted. When foe field 
width is non-zero, the inserters will insert at least that many characters, using 
foe fill duvacter to pad foe value; if foe value being inserted requires fewer 
than fidd-widfo characters, to be represented. However, the numeric mserters 
never truncate values, so if the value bdng inserted will not fit in fidd-width 
dtaracters, iitore than fidd-width characters will be output The fidd widfo is 
al%vays interpre te d as a mininum number of diaracters; there is rK> direct way 
to ^pedfy a maximum number of characters. The fidd width format variable 
is reset to the defoult (zero) after eadt ittsertion or extraction, and in this y ny 
it bdiaves as a parameter for insertiorts aixl extractions. A parameterized 
manipulator, setw is also available for setting the widfo, see mamp(3C++). 

iss.widfo() 

Returns foe "field widfo" format variable. 

User-defined Format Flags 

Several functiorts are jx’ovided to allow users to derive classes from dass ios that require 
additional format flags or variables. The two static member functions iosnxalloc and 
iossbitalloc allow several such classes to be used together without interference. 

bsiosxbitallocO 

Returns a long with a single, previously unallocated, bit set. This allows 
users who need an additional flag to acquire one, and pass it as an argument 
to iosssetfO, for example. 

i=ios=xallocO 

Returns a previously unused index into an array of words available for use as 
format state variaUes derived classes. 

IssJwordfi) 

When i is an index allocated iosmcalloc, iwordO returns a reference to the 
ifo user-defined word. 

vp=s.pword(i) 

When 1 is an ittdex allocated by iosnxalloc, pwordO returns a reference to the 
ifo user-defined word. pwordO is foe same as iword except that it is typed 
difrerently. 

Other members: 

sbss.rdbuf() 

Returns a pointer to the screainbuf associated with s when s was con¬ 
structed. 
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iosssyncjwitfajstdioO 

Solves proUems that arise when mixii^ stdio and iostreams. The first time it 
is called it will reset the standard iostreams (cin, cout, cerr, clog) to be 
streams using stdiobufs. After that input and output using these streams 
may be mixed with ir^t and output using the corresponding FILES (stdin, 
stdout, and stderx) and will be propeiiy synchronized. syiic_witfa._stdio() 
makes cout and cerr unit bufiered (see ios: :unitbuf attd ios:: stdio 
above). Invoking ^c_wifii_stdioO degrades perfoimartoe a variable amount, 
dependmg cm die length of die strings beir^ inserted (shinier strings incur a 
lai^ p er fo rmance hit). 

oosp«s.de(osp) 

Sets the "de" variaUe to ctf, and returns its previous value This variaUe sup¬ 
ports automatic "flushii^” of loss. If die tie variaUe is noiMiuIl and an ios 
needs more characters or has diaracters to be consumed, die ios pointed at 
by die de variaUe is fludied. By default, cin is tied initially to cout so diat 
atterr^its to get mcne characters ftom standard input result in flushing stan¬ 
dard output Additionally, cerr and clog are tM to cout by default For 
odier loss, the de variable is set to zero by default 

osp«s.de() 

Returns die "de* variable. 


Bnilt'in Manipulators: 

Some convenient manipulators (functions diat take an iosS, an istreams, or an ostreams 

and return thdr argument see mamp(3C+*)) are: 

sr«dec 

sz»dec 

These set the conversum base format flag to 10. 

sr«hex 

sr»hex 

These set the conversion base format flag to 16. 


sr«oct 

sc»oct 

These set die converskm base format flag to 8. 

sr»ws Extracts whitespace diaracters. See istream(3C-¥*). 

sr«endl 

Ends a line by inserting a newline diaracter and flushing. See ostream(3C++). 
sr«ends 

Ends a string by inserting a nuIKO) character. See o^ream(3C**). 
sr«flush 

Flushes outs. See ostrem(3C+*). 

Several parameterized manipulators that operate on ios objects are described in mamp(3C**): 
setw, setfill, se^iredsion, sedosflags, and zesedosflags. 

The strearobuf assodated widi an ios may be manipulated by odier methods dian dirot^ 
the ios. For example, duuacters may be stored in a queudike streaidjuf dvough an 
ostream while they are beir^ fetched through an isbream. Or for effidency some part of a 
program may choose to do streambuf operadons direedy radier than throu^ the ios. In 
most rasps the program does not have to worry about this possibflity, because an ios never 
saves informadon about the internal state of a streardbuf. For example, if the streambuf 
is repositioned between extraction operations the extraction (input) will proceed normally. 
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CAVEATS 

The need for sync_witfi_stdio is a wart The old stream package did ttiis as a default, but in 
die iostream padcage unbu^ered stdiobufs are too inefficient to be the default. 

The stream padcage had a constructor diat took a FILE* argument. This is now rqjlaced by 
stdlostreaiB. It is not dedared even as an obsolete form to avoid having iostream. h 
depend (HI stdlo.h. 

The old stream pack^ allowed copying of streams. This is disallowed by the iostream pack¬ 
age. However, objects of type Istreamjirlthassign, ostreaajwithasslgn, and 
iostreaa^wlthassign can be assigned to. Old code using copying can usually be rewritten 
to use pointers or these dasses. (The standard streams cin, cout, cecr, and clog are 
members of "urithassign* (dasses, so diey can be assigned to, as in cin - inputfstream.) 

SEE ALSO 

IOSJNTRCX3C++), streandHifOC^), istieam(3C-H>), ostieam(3C>M-), manip(3C<i>-»^). 
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NAME 

istream - formatted and unformatted input 
SYNOPSIS 


streampos; 


seekjdir { btg, car, end }; 

open_node { is, out, ate, app, tnuc, nocreate, noreplace } ; 
for cootreHiBg format */ 

{ skipi*s=01, 

lef^2, righta04, iatcraaisOlO, 
dccsdttO, oct s dMO, hexsOlOO, 

sfaowtmseaOZOO, showpoiatafMOO, Bppercase=01000, sliowpos=02000, 
sciaitific=04000, fitedsOlOOOO, 
aaitbnraOlOOOO, stdio=(M0000 }; 

// and bts of other stuff, see ios(3C-*-*-) 

} ; 


#inciude <iostrcamJi> 

typedef kmg streamofT, 

class ios { 

public 

ennm 
eoum 
/* flags 


dass istream : pubGc ios { 
public 

istreamfstreambnf*); 

iut gcountO; 

istream& getfchar* ptr, int leu, char ddlms*\a*); 

istream& getCunsigBed char* ptr^nt lea, char deCmsNi’); 


istreamdc getfuasigned cliar&); 

istream& get(char&); 

istream& get(streambBf& sb, char delim 

int getO; 

istream& gediaefchar* ptr, iat lea, char delimsVi*); 

istream& getUaefnasigaed char* ptr, iat lea, char (feiIm=*Va*); 

lstream& ^noreOnt leBsl,iat ddimsEOF); 

iat ipfofiat aeedaO); 

iat ped^; 

istreamde putbackfcfaar); 

istream& readfchar* s, iat a); 

istremn& readfuasigaed char* s, iat a); 

istream& sedcgCstreampos); 

istream& seekgfstreamotr, seekjdir); 

iat syacO; 

streampos teilgO; 


istream& operator»<diar*); 

istream& operator»(char&); 

istreamdc operator»(siiort&); 

istream& operator»Ont&); 

istreani& operator»Oong&); 

istreani& operator»(float&); 

istreamdc operator»(dooble&); 

istream& operator»<uBsigned char*); 

istream& operator»(onsigned char&); 
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}; 


istreamic operator»(tinsigned short&); 

istreamic operator»(unsigned int&); 

tstreain& opeFator»(unsigned Iong&); 

istreain& openitor»(streainbuf*); 

istreain& operator»(istream& (*Kistream&}); 
istreain& operator»(ios& (*Kios&)); 


dass istreain_withassign : public istream { 

istream_witfiassig;nO; 
istream& operatc^istreain&); 

istreamSc oper ato rg( s tre a inbuD; 

}; 

extern istream_withassig;n dn; 

istTeain& %vs(istfeain&) ; 

ios& dec(ios&) ; 

ios& hex(ios&) ; 

ios& oct(ios&) ; 

DESCRIPnON 

istceans support interpretation of characters fetched feom an associated streanbuf. These 
are commonly referred to as ii^nit or extraction operations. The istream member functions 
and rdated functions are described bdow. 

In the foDowing descriptions assume that 

— ins is an istream. 

— inwaisan istreamjwithassign. 

— inspisa istream*. 

— cisa chare 

— delim is a char. 

— ptr is a char* or unsigned char*. 

— sb is a streambuf &. 

— i, n, len, d, and need are ints. 

— posisa streampos. 

— off is a streamoff. 

— dir is a seek_dir. 

— manip is a function with type istreaais (*) (istreamfi). 

Constructors and assigrunent; 
istieamfsb) 

Initializes ios state variaUes and associates buffer sb with the istreaau 

bteeam^witfaassignO 

DoesrK) initializatkm. 

inswi^sb 

Associates sb with inswa and initializes the entire state of inswa. 
inswasins 

Associates ins>>xdbnfO with inswa atwl initializes die «itire state of inswa. 

Ir^ut prefix function: 

i s insJpfxfneed) 

If ins's error state is rKm-zero, returns zero iiiunediateiy. If necessary (and if it 
is non-null), any ios tied to ins is flushed (see the description iosetieO in 
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ios(3C++)). Flushii^ is considered necessary if either needssO or if drere are 
fewer than need diaracters immediatdy available. If ios:: skipws is set in 
ins.flagsO and need is zero, then kad ^ whitespace diaracters are extracted 
ftom ins. returns zero if an enor occurs while skipini^ whitespace; oth¬ 
erwise it returns non-zeco. 

Formatted input functions caO ipMO), ndiile unformatted input functions call ipfxfl); 

see below. 

Focmatted ii^mt functions (extxactocah 

ins»x Calls ipfidO) and if foat returns non-zero, extracts characters from ins and con¬ 
verts them according to the type of x It sto re s the converted value in x 
Errms are indicated by setting ^ error state of ins. ios:: failblt means 
that diaracters in were not a represen tation of die r eq ui red type. 
ios::badblt indicates that attempts to extract characters faded, ins is 
always returned. 

The detads of conversion depend on die values of ins's format state flags and 
vaiiaUes (see iosOC-M-)) and the type of x Except that extractions diat use 
widdi reset it to 0, die extraction op er a tors do not change die value of 
ostzeasfs format state. Ext ract o r s are defined for the followup types, with 
conversion rules as described bdow. 

char*, unsigned char* 

Charactets are stored in the array pointed at by x until a white^aoe 
character is found in ins. Ihe tenrdnatiiig Mdiite^iaoe is left in ins. If 
ins.widdiO is non-zero it is taken to be the size of die array, and no 
mote than ins.widdiO-1 characters are extracted. A terminating null 
character (0) is always stored (even when nodiing else is done because 
of ins's error status). ins.widtfaO is reset to 0. 

chars, unsigned chars 

A character is extracted and stored in x 

Shorts, unsigned shorts, 

Ints, unsigned Ints, 
longs, unsigned longs 

Characters ate e x tr a cted »d ccmverted to an integral value according 
to the conversion specified in ins's forma t flags, inverted characters 
are s tored in x The first character may be a sign (4 or -). After that, 
if los::oct, los::dec, or los::hex is set in ins.fligsO, the 
conversion is octal, dedonal, or hexadedtnal re^iectivdy. Conversion 
is terminated by the first "non-digit,* ivhich is 1^ in ins. Octal digits 
ate the diaracters 'O' to '7'. Dedtnal digits are die octal digits (dus '8' 
and '9'. Ifeadecitnal digits are the decimal digits plus die letters 'a' 
duough 'f' Cin either upper or lower case). If none of die conversion 
base fonnat flags is set, then the number is inter(»eted according to 
C-M* lexical conventkms. That is, if die first characters (after the 
optional sign) ate Oz or OX a hexadedtnal converaon is p er form ed on 
following hexadedmal digits. Otherwise, if the first chaiacter is a 0, 
an octal oxiversion is p er for med, and in all other cases a dedmal 
conversion is p erfo r med. Ios:: failblt is set if there are no digits 
(not coundi^ the 0 in Oz or OX) during hex conversion) available. 

floats, doublea 

Converts the characters according to C-t-t- syntax for a float or double, 
and stores die result in x. ios:: failblt is set if there are no digits 
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available in ins or if it does not begin with a well formed floating 
point number. 

The type and naine(operator») of die extraction operations are dhosen to give a 
convenient ^mtax for sequences of iiqmt operations. The t^ierator overloadii^ of C-m- 
permits extraction functions to be dedared for user-defined classes. These operations 
can then be used widi the same syntax as die member functions described here. 

ins»sb 

If iosJpfxfO) returns non-aoo, extracts diaracters from ios and inserts them 
into d>. Extraction stops when BOF is readied. Always returns ins. 

Unfonnattcd input fancdons: 

These functions call ^>fx(D and proceed only If it returns non-zero: 
insp3:&ins.gcl!(ptr4eivdelim) 

Extracts diaracters and st(»es diem in the byte array beginning at ptr and 
extending for len bytes. Extraction s top s when delim is encountered (delim is 
left in ins and not stored), ndien ins has no more diaraders, or when die array 
has only one left get always st o re s a terminating null, even if it doesn't 
extract ar^ characters foom ins b w a u s e of its error status, ios:: failbit is 
set onfy if get encounters an end of file before it stores any characters. 

insps<rins.get(c) 

Extracts a single character and stmes it in c 
inspgfidnsgedsb^ielim) 

Extracts diaracters foom ins^dbufO and stores them into sb. It stops if it 
encounters end of file or if a store into sb fails or if it encounters delim (which 
it leaves in ins), ios:: failbit is set if it stops because die store into sb fails 

izins.get(). 

Extracts a diaracter and returns it i is EOF if extraction encounters end of 
file, ios: :failbit isnever set 

insps&ins.getline(ptr4e n ,d e ii m ) 

Does die same diir^ as ins.get(ptr4etvdellm) widi die exception diat it extracts 
a terminating delim diaracter from ins. In case delim occurs when exactly len 
characters have been e x tracted, termination is treated as beir^ due to the array 
beirig filled, and diis delim is left in ins. 

insp»&ins.ignoie(rvd) 

Extracts and throws away up to n characters. Extraction stops prenmturely if 
d is extracted or end of file is readied. If d is EOF it can never cause termina¬ 
tion. 

insp«Arinsjrad(pti;n) 

Extracts n characters and stores diem in the array beginning at ptr. If end of 
file is readied before n characters have been extracted, read stores whatever it 
can extract and sets ios::failbit. The number of characters e x tract e d can 
be determined via insgcountO. 

Odier members are: 

isins.gcountO 

Returns die number of characters e x tracted by the last unformatted irqnit func¬ 
tion. Formatted input functions may call unformatted input functions and 
therein reset this number. 

isins.pedc() 

Begins by calling itis.iphc(l). If that call returns zero or if ins is at end of file. 
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it returns EOF. Otherwise it returns the next character without extracting it 
insps&ins.patback(c) 

Attempts to back up insjdbufO. c must be the diaracter before insjdbufO's 
get pointer. (Unless other activity is modifying ins.rdbuf() this is die last char¬ 
acter extracted horn ins.) If it is not die e^ect is undefined, putbadc may fail 
(and set the error state). Aldiough it is a member of istreanv pudiack never 
extracts diaracters, so it does not cad ipfx. It ivill, however, return nvithout 
doing anydiing if the error state is non-zero. 

is&ins.^ncO 

Establishes consistency between internal data structures and die external 
source of diaracters. Calls inszdbiifO->s)mcO, whidi is a virtual function, so 
the details dqiend on the derived dass. Returns EOF to indicate errors. 

ins»nian4> 

Equivalent to manip(ins). ^rntactically this looks like an extractor operation, 
but semantically it does an artritraiy operation rather than converting a 
sequence of characters and storing the result in manip. A predefined manipu¬ 
lator, ws, is described bdow. 

Member functions related to portioning: 
insps4dns.seekg(of^dir) 

Repositions in&zdbafO's get pointer. See sbi^:pub(3C*+) for a discussion of 
positioning. 

insp=&ins.seekg(pos) 

' Repositions ins.zdbafO's get pointer. See sbuf;pub(3C*+) for a discussion of 
positioning. 

possins.tellg() 

The current position of iosjdbufO's get pointer. See sbuf.pub(3C++) for a dis¬ 
cussion of positioning. 

Manipulaton 

ins»ws 

Extracts %diite^»oe diaracters. 
ins»dcc 

Sets die conversion base format flag to 10. See us(3C*+). 
ins»hex 

Sets the oonver^n base format flag to 16. See ios(3C**). 
ins»od 

Sets die conversion base format flag to 8. See iosOC-m-). 

CAVEATS 

There is no overflow detection on conversion of integers. There should be, and overflow 
should cause die error state to be set 

SEE ALSO 

ios(3C++), sbuf.pubOC'M'), manip(3C-M-) 
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NAME 

manipulators - iostream out of band manipulations 
SYNCH>SIS 

fincliide <io6 t r f a M h> 

INadade <iomaeipJi> 

lOMANIPdedartCD ; 

dasB SMANlPCr) { 

9MAN1P(TX ios& (*)(iosft,T), T); 

IHcad istreaB& opct»tm»(istrw<r, SMANIP(T)&): 

frtad ostrcaaft opcratar«(ocbrcHBl^ SMANl]PCr)&); 

}; 

dass SAPP(D { 

SAPPCrX iostc f*Kios&,T)); 

SMANIPCT) operalorOCr); 

}; 

dass IMANIPCr) { 

IMANIP(TK istrcaB& (•X’Btream&J), T); 

IHend istreaB& operator»<islreMi&* IMANIPfD&); 

}; 

dass lAPPCD { 

lAPPCrX istrcaiB& (*Kistream&,T»; 

IMANIP(T) operatorCKT); 

}; 

dass OMANIPCD { 

(MiANIP(TK ostrcain& (*Kostrcaai&,T), T): 

friend ostrcani& operator«(ostreaoi&, (WilANIP(T)&); 

}; 

dass OAPPCT) { 

OAPPCTK ostreani& (*Kostream&,T)); 

OMANIP(T) opcratorOCT); 

}; 

dass IOMANIPCT) { 

lOMANIPCTK iostreani& (*)Qastream&,T), T); 

friend istreain& operator»<iostreani&, IOMANIP(T)&); 

friend ostreani& operator«<iostreani&, l(WilANIP(T)&); 

}» 

dass lOAPPCD { 

IOAPP(TK iostream& ^)(iostreani&,T)); 

IOMANIP(D operatorOCT); 

}; 


lOMANIPdeclareOnt); 

lOMANIPdedareOong); 


SMANIPGong) 

SMANIPfint) 

SMANIPGong) 

SMANIPOnt) 

SMANIPGnt) 


resetiosflagsGong); 
setfiOfint); 
setiosflagsGong); 
setpredsiooGnt); 
set^int w); 
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DESCRIPTION 

Manipulators are values Aat may be inserted into" or "extracted from" streams to achieve 
some effect (other than to insert or extract a value representation), with a convenient syntax. 
ThQ^ enable one to embed a funebon call in an expression containing series of insertions or 
extractions. For example, the predefined manipulator for ost reams, flush, can be used as fol¬ 
lows: 

cout« flush 

to flush cout. Severd iostream dasses supply manipulators, see ws(3C++), BfreBmOC-M-), and 

ostreem(3C**). flush is a sun|^ manipulator; some manipulators take arguments, such as the 
pi^efined ios ^pula^ setfill and setw (see below). The header file iomanip. h sup- 
{dies macro definitions whidi progranuners can use to define new parameterized manipulators. 

IdeaUy, the types idating to manqnilatois wrould be parameterized as "templates." The maaos 
defined in ionanip.h are used to simulate ten^tes. lOMANlPdedaieCT) dedaies flie vari¬ 
ous dasses and operators. (All code is dedaied inline so fliat no separate definitions are 
required.) Ead\ of the other Ts is used to construct the real names and therefore must be a 

single identifer. Each of the other macros also requires an identifier and expands to a name. 

In the foUowii^ descriptions, assume: 

— t is a T, or type name. 

— sis an ios. 

— i is an istream. 

■— o is an ostceasL 

— io is an iostceam. 

— f is an loss (*) (iosC). 

— ifban istreama (*) (istceamC). 

— of is an ostreamc (*) (ostreana). 

— iofisan iostreaaa (*) (iostceama). 

— nisan int. 

— lisa long. 

s«SMANIP(T)(f4) 

s»SMANlP(TKf4) 

s«SAFP(IT(fMt) 

s»SAPPCn(£Mt) 

Returns f(sA where s is the left operand of the insertion or extractor operator (U., s, i, o, or 


i»IMANIP(TKif,t) 

i»IAPP(TXifMt) 

Returns if(i,t). 

o«OMANIP(TKof 4 ) 

o«OAPP(TMofMt> 

Returns of(o^. 

io«IOMANIP(TKiof 4 ) 

io»IOMANIP(TKiof 4 ) 

UK<IOAPP(TMiofMt) 

ia»IOAPP(TKiofMt) 

Returns iof(io,t). 

iomanip.h contains two dedarations, lOMANIPdeclare (int) and lOMANlPdeclare (long) and 
»me manipulators that take an int or a long argument These manipulators all have to do with 
dianging the format state of a stream, see ios(3C++) for further details. 
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o«setw(n) 

i»settv(n) 

Sets the fidd widttt of the stream (left*4tand operand: o or i) to n. 

o«setfill(n) 

i»$ctfill(n) 

Sets the fill character of the stream (o or i, or) to be n. 

o«setpredsion(n) 

i»se^xedsion(n) 

Sets the precision of the stream (o or 0 to be n. 

o«setiosflags(l) 

i»setiosflags(D 

Turns on in the stream (o or i) file format flags marked in L (Calls o.setfQ) or Lsetffl)). 

o«resetiosflags(l) 

i»fesetiosflags(l) 

dears in file stream (o or i) file format tnts specified by L (Calls o.setf(04) or Lsetf(0,l)). 

CAVEATS 

Syntax error s will be re po rte d if lOMANlPdedareCD occurs more than once in a file with the 
sameT. 


SEE ALSO 

ios(3C-M>), istream(3C*H>), ostream(3C-M>) 
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NAME 

ostream - formatted and unformatted output 
SYNOPSIS 

finchide <iostreamJi> 


tjpedef long streamoff, streaaqMs; 

class MS { 

pabik: 

entim seek_dir { beg, cor, end }; 

enom opeB_BBode { in, ont, ate, app, tnuK, nocreate, norep la ce } ; 

eanm { skipussOl, 

lefIMIZ, liglfodM, intemalsOlO, 
decsOZO, ocfo040. heisOlOO, 

showbaseaOZOO, dMwpointsOdOO, appercasesOlOOO, sboirpossOZOOO, 
sdentificalHOOO, fisedaOlOOOO, 
naitbafsOZOOOO, stdio=040000 }; 

// and lots of other stuff, see iosiSC**) 

} ; 


class ostream : public ios { 
public 


ostream& 

int 

ostream& 

ostream& 

ostream& 

streampos 

ostream& 

ostream& 

nctr » ainAr 

ostreaB& 

ostream& 

ostream& 

ostream& 

ostream& 

ostream& 

ostreani& 

ostream& 

ostream& 

ostreani& 

ostream& 

ostream& 

ostreamde 

ostream& 


dass ostream_withassign { 

istreamde 

istreamd; 

}; 


ostreain(streambuf*); 

flusbO; 

opfxO; 

pnt(cliar); 

seekp^treampos); 

seekpCstreamofT, sedc_dir); 

tellpO; 

write(coast char* ptr, int n); 

wr ite (coos t undgaed ckar* ptr, int n); 

operator«(const char*); 

operator«(ciiar); 

operator«(sliort); 

opcrator«^); 

operator«(loag); 

operator<<float); 

opcrator«(dooble); 

operator«(oasigned char); 

operator«(nasigned short); 

operator«(onsigned int); 

operator«(nnsigned long); 

operator«(void*); 

opcrator«(streambnf*); 

opcrator<<ostrcamdc (*Xostream&)); 

operator«(ios& (*)(ios&)); 


ostream_withass^O; 

operator=(istream&); 

operator=(streambur*); 
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exton ostream_withassign cout; 
extern ostream_witfaassign cen; 
extern ostream_wiiiiassign clog; 


ostreamic 

ostieam& 

ostieam& 


endl(ostreain&); 
ends(ostreain4c) ; 
flttsh(o$tream&) ; 


ios& 

ios4c 

ios& 


dectiosie) ; 
hex(iosdc); 
oct(ios&) ; 


DESCRIPnON 


ostreans support insertion (storirig) into a atreanbuf. These are coiniiK>nly referred to as 
ou^t operations. The ostraan member functions aitd related functions are described 
bdow. 

In the fcdlowing descriptions, assume: 

— outs is an ostrean. 

— ontswaisan ostceaai^trlthassign. 

— outsp is an ostream*. 

— c is a char. 

— ptr is a char* or unsigned char*. 

— sb is a streaiDbuf * 

— i and n are ints. 

— posisa streaiqpos. 

— off is a streamoff. 

— dir is a seek_dir. 

— manip is a fuiKtion with Qrpe ostreanc (*) (ostream&). 

Constructors and assignment: 


ostreamfsb) 

Initializes ios state variables and associates bu^ sb tvith the ostream. 
ostream_widiassign() 

Does no initialization. This allows a file static variable of this Qrpe (cout 
examfde) to be used before it is omstnicted, p>rovided it is assigned to first. 

outswassb 

Associates sb %vith swa and initializes foe entire state of outswa. 
inswasins 

Associates lns->idbafO with swa and initializes foe entire state of outswa. 


On^ttt prefix function: 

isoats.(^fxO 


If oats's error state is nonzero, returns innmediatdy. If outs.tieO is non-null, it 
is flushed. Returns non-zero except when outs's error state is nonzero. 


Ou^rat suffix fonctioxu 


osfx() Performs "suffix" actions before returning horn mserters. If ios: :unicbu£ is 
set, osbcO flushes the ostrean. If ios: :stdio is set, osfxO flushes stdout and 
stdecc. 

osficO is called by all predefined inserters, and should be called 1^ user-defmed insert¬ 
ers as well, after any direct manipulation of foe stceanbuf. It is not called the 
binary output fuitctions. 


Formatted output functions (inserters): 
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OtttS«X 

First oats.op6c() and if Aat returns 0, does nothing. Otherwise inserts a 
sequence of dwuacters r e pr c s en tii^ x into outsjxIbufO. Errors are iiKiicated by 
settii^ the error state of oats, outs is always returned. 

X is converted into a sequence of characters (its representation) according to 
rules that depertd on x's type aird oats's format state flags and variaUes (see 
tosOC'M’)): Inserters are defined for flie following Q^^es, with conversion rules 
as described bdow. 

char* The rep r ese ntation b flie sequence of draiacters up to (but not indud- 
ing) die terminating mill of string x points at 

any integml type except char and unsigned char 

If X b positive die lepresentatkm contains a sequence of dedmal, octal, 
or hexadecimal digHs with no leading zeros according to wheflier 
ios: :dec, ios: :oet, or ios: :bez, reqxctiveiy b set in ios's for¬ 
mat flags. If none of those flags are set, conversiem defaulb to 
dedmaL If x b zero, die representatiem b a single zero characteKO). If 
X b negative, dedmal conversion converts it to a minus sign (-) fol¬ 
lowed by dedmal digits. If x b positive and ios:: showpos b set, 
decimal converdon converts it to a plus sign {*) followed by dedmal 
digits. Hie odier conversions treat all values as unsigned. If 
ios:: shoirtiase b set in ios's format flags, the hexadedmal re p reser v- 
tation contains Ox before die hexideciinal digits, or OX if 
ios::uppercase b set If ios: :shoifoase b set die octal 
r ep r e s e ntation contains a leading 0. 

void* Pointers are converted to integral values and then conver te d to hexade¬ 
cimal numbers as if ios: :sho«foase were set 

float, double 

The arguments are converted according to die current values of 
oats.ptecbiohO, oats.widfiiO and oats's format flags 
ios:: scientific, ios:: fixed, and ios: :i^percase. (See 
ios(3C*+).) The default value for oats.precbionO b 6. If neither 
ios::scientific nor ios::fixed b set eidier fixed or sdendfic 
notation b chosen for the repr ese ntation, dependir^ on the value of x. 

char, unsigned char 

No spedal conversion b necessary. 

After die reixesentation b determined, padding occurs. If oats.widdi() b 
greater dian 0 and die r e p rese ntation contains fewer than oats.widthO diarac- 
ters, then enou^ oats.fiI10 characters are added to bring the total number of 
characters to ios.widdi0. If ios::left b set in ios's format flags, die 
sequence b left-adjusted, diat b, characters are added after die diaracters 
determined above. If ios:: right b set die padding b added before the 
diaracters determined above. If ios: :intemal b set, die paddir^ b added 
after any leading sign or base indication and before the characters diat 
r ep r e se nt the value. ios.widdi(> b reset to 0, but all other format variaNes are 
unchanged. The resulting sequence (padding plus representation) b inserted 
into ootszdbofO. 

outs«sb 

If ottt 5 .opfx() returns non-zero, the sequence of characters that can be fetdied 
from sb are inserted into outs.rdbttf(). Insertion stops when no more charac¬ 
ters can be fetdied from sb. No padding b performed. Always returns oats. 
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Uafonnattcd on^ut functions: 

oal^ps^ttts.paMc) 

Inserts c into ontsjrdbufO. Sets the error state if the insertion ^is. 
oatsps&outs.«irxite(s«n) 

Inserts ttie n diaracters staitiiig at s into outsjdbufO. These characters may 
indude zeros (Le., s need itot be a null terminated string). 

Ottier member functions: 

outspat&ontsJhishO 

storing characters iiUo a streanibuf does not always cause them to be con¬ 
sumed (eg., written to die external file) immediately. fluskO causes any char¬ 
acters ttiat may have been stored but not yet consumed to be consumed by caU 
ling ontsjtc&iifO>>sync 

onts«manip 

Equivalent to man^outs). ^ntactkalfy this looks like an insertion operation, 
but semantical^ it does an arbitiaiy tolerations rather than converting manip 
to a sequence of diaiaclers as do die insertion operators. Predefined manipu¬ 
lators are described bdow. 

Positioning functions: 

oatsp«4dns3ed:p<o£Cdir) 

Repositkms outsjdbufO's put pointer. See Ai^jpubOC**) for a discussion of 
posittonii^ 

ontsp«tomts.seckp(pos) 

Repositions ontsadbnf(rs put pointer. See sbuf.pulK3C<M-) for a discusnon of 
positioning. 

po5souts.tellp0 

The current potion of onts^dbufO's put pointer. See sl«/.puW3C++) for a dis¬ 
cussion of positionii^. 

Manipulators: 

onts«endl 

Ends a line by inserting a newline character and flushing. 
outs«ends 

Ends a string \ 3 y inserting a nulKO) diaracter. 

outs«fliish 

Fludiesouts. 

oufs«dec 

Sets die conversion base format flag to 10. See iosOC-m-). 
oats«faex 

Sets the ccmveision base format flag to 16. See iosfSC-M-). 
oats«oct 

Sets die conversion base format flag to 8. See iosOC-M-). 

SEE ALSO 

ios(3C*M>), sbuf.pub(3C-«-i'), manipOC-M-) 
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NAME 

streambuf - interfooe for derived classes 
SYNOPSIS 

Bindiide <iostreamJ» 


typedef long streamofT, streampos; 

dass ios { 

public 

ennin seek_dir { beg, cur, end }; 

enum openjnode { in, out, ate, app, tninc, nocreate, noreplace } ; 

// and lots of other stuff, see ias(3C++) ... 


} ; 


dass streambof { 
public 


protected: 


public 


void 

streambufO ; 

streambof(diar* p, int len); 
dbpO ; 

int 

aOocateO; 

char* 

baseO; 

int 

blenO; 

char* 

ebackO; 

char* 

ebufO; 

char* 

egpfrO; 

diar* 

epptrO; 

void 

gbump(int n); 

char^ 

gptrO; 

cfaar^ 

pbaseO; 

void 

pbumpOnt n); 

cbar^ 

PPtrO; 

void 

setg(cliar* eb, char* g, char* eg); 

void 

se^cfaar* p, char* ep); 

void 

settKchar* b, char* dr, int asO); 

int 

nnbufreredO; 

void 

unbuireredCint); 

virtual int 

doaUocateO; 

virtual 

’StreambufO ; 

virtual int 

pbackfafl(int c); 

virtual int 

overflow(int csEOF); 

virtual int 

underflowO; 

virtual streambuf* 

setbuf(diar* p, mt lot); 
virtual streampos 


}; 


■ ' ■-'----— I /f 

virtual streampos 

seekof!(streamofr, sedc_dir, int =ios::in|ios:out); 
virtual int $yncO; 
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DESCRIPnON 

streambufs implement the buffer abstraction described in siw/.p«6(3C++). However, the 
streambuf class itself contains only basic members for manipulating the characters and nor¬ 
mally a class derived from streambuf will be used. This man page describes the interface 
n^ed by programing who are coding a derived dass. Broadly speaking there are two 
hiittls of member frincbons described here. The non-virtual functions are provided for mani¬ 
pulating a streambuf in ways that are appropriate in a derived class Their descriptions 
r^eal details of the iir^lementation diat would be inappropriate in die public interface. The 
virtual functioiB permit the derived class to specialize the streambuf class in ways appropri¬ 
ate to die specific sources and. sinks diat it is implementing. The descriptions of the virtual 
functions exfriain the oUigations of the virtuals of die derived dass. If the virtuals bdiave as 
specified, the streambuf will bdiave as qiedfied in die public interface. However, if die vir¬ 
tuals do not behave as ^xdfied, then the streambuf may not bdiave properly, and an ios- 
tream (or any other code) diat relies on proper bdiaviOT of the streambuf may not behave 
properly ath». 

In the foQowing descriptions assume: 

— sb is a streambuf*. 

— i and n are ints. 

— ptr, b, eb, p, ep, eb, g, and eg are char*s. 

— c is an int diaracter (positive or EOF)). 

— pos is a streampos. (See sbt^.jnib(3C*+).) 

— off is a streamoff. 

— dir is a seekdir. 

— mode is an int representing an open_mode. 

Constructors: 

streambuff) 

Constructs an en^ty buffer corresponding to an entity 
streambuf(b4en) 

Constructs an emp^ buffer and then sets up the reserve area to be the len 
bytes starting at b. 

The Get; Pni and Reserver area 

The protected members of streanibuf present an interface to derived organized 

around three areas (arrays of bytes) managed cooperatively by the base and derived Oaccoc 
They are the gd area, the put area, and die reserve area (or buffer). The get and the put areas 
are normally disjoint, but they may bodi overiap the reserve area, whose primary purpose is to 
be a resource in which space for the put and get areas can be allocated. The get and the put 
areas are chan^ as characters are put into and gotten from the buffer, but the reserve area 
normally remains fixed. The areas are defined by a ccdlection of char* values. The buffer 
abstraction is desoibed in terms of pointers that point between diaracters, but die char* 
values must point at chars. To establish a conespondence the char* values should be 
thou^t of as pointing just before the i^e di^ really point at 

Functions to examine the pointers 
ptra:sb->base() 

Returns a pointer to die first byte of the reserve area. Space between sb- 
>base() and sb->ebuf() is the reserve area. 

ptr=sb->ebackO 

Returns a pointer to a lower bound on sb->gptr(). Space between sb'>eback() 
and sb->gptrO is available for putbadc. 

ptrssb->ebaf() 

Returns a pointer to the byte after the last byte of the reserve area. 
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ptr«sb->cgpti<) 

Returns a pointer to the byte after the last byte of the get area. 
ptra:$b>>cppti() 

Returns a pointer to the byte after the last byte of the put area. 

ptFBSb->gptt<) 

Returns a pointer to Ae first of the get area. The availaUe characters are 
those between sb->gpliO and sb->cgptiO. The next duuacter fetched will be 
*(sb->Q>trO) unless sbocgptzO is less than or equal to sb>>gptiO. 

ptFssb>>pbaseO 

Returns a pointer to die put area base. Oiaiacters bet%veen sb>>pbJBe() and 
sb>>pptxO have been stored into the buftier and not yet consumed. 

ptra>sb>>pptiO 

Returns a pointer to the first byte of die put area. The space between sb- 
>pptiO and sboepptiO is die put area and diaiacters will be stored here. 

Functions for setting die pointers 

Note diat to indicate that a particular area (get, put, or r e se r ve ) does not exist, all die associ¬ 
ated pointers should be set to zero. 

sb>>se&(b, eb, D 

Sets bascO and ebufO to b and eb respecdvdy. i controls whether the area 
win be subject to automatic ddedon. If i is rum-zero, dien b win be dieted 
when base is changed by another can of sedrO, or udien the destructor is 
caned for *sb. If b and eb are both nun then we ss^ that there is no reserve 
area. If b is non-nun, there is a reserv e area even if eb is less than b and so 
the reserve area has zero length. 

sb->seqKp/ ep) 

pptiO to p, pbaseO to p, and epptiO to ep. 
sb->setg<eb, g, eg) 

Sets ebackO to eb, gptcO to g, and egpItO to eg- 

Other non-virtual members 
issb->allocateO 

Tries to set up a re s e r ve area. If a reserve area already exists or if sb* 
>anba£feredO is nonzero, allocaleO returns 0 without doing an 3 rthii^. If die 
atteirqit to adocate ^lace fads, allocateO returns EOF, otherwise (aUocation 
succeeds) anocateO returns 1. allocateO is not called by any n5n-virtual 
member function of stceaaibuf. 

i«sb->blenO 

Returns the size fin chacs) of the current reserve area. 

dbpO Writes directty cm file desoqitm’ 1 infocmaticn in ASCII about the state of the 
buffer. It is intended for ddmgging and rmthing is ^ledfied about die form of 
die output It is considered part of the p ro t ected interface because die infor¬ 
mation it prints can only be understood in rdatkm to that inte rface, but it is a 
pulfik furicdtm so that it can be called aiqndiere dutir^ debugging. 

sb->gbnmp(n) 

Increments ^b<) by n vdiich may be positive or negative. No checks are 
made cm vdiether the new value of gptiO is in bounds. 

$b->pbamp(n) 

Increments pptiO by n whidi may be positive or negative. No diecks are 
made cm whether d« new value of pptcO is in bounds. 
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sb->anbii£feted<i) 

ia*b>>iinbtt£feredO 

There is a private variaUe known as sb's buffering state. sb->axibttffered(i) 
sets the value riiis variable to i and sb>>unbn£fered() returns rite current 
value. This state is independent of the actual allocation of a reserve area. Its 
primary purpose is to control ttriieriier a reserve area is allocated automatically 
by allocale. 

>^xtaad member functions 

Virtual functions may be redefined in derived classes to specialize rite behavior of stream- 
bufs. This section describes rite bdtavior ritat these virtual functions ^uld have in any 
derived classes; the next sectkm describes rite behavior ritat these functions are defined to have 
inbasedass stceanbuf. 

i«sb>>doalloeatcO 

Is called when allocaleO delermiites ritat space is iteeded. doallocateO is 
required to call setttO to provide a reserve area or to return EOF if it canitot. 
It is oofy ca lled if sb>>nnba£feredO is zero aitd sb>>bascO is zero. 

isovezflow(d 

Is called to consume characteis. If c is not EOF, oveiflowO also most either 
save c or consume it Usualty it is called when the put area is full and an 
attenqjt is being made to store a new diaracter, but it can be called at other 
times. Ute normal actkm is to consume the characters between pbaseO and 
PptiO, call se^ to establish a new put area, and if c!»EOF store it (using 
tpubcO). sb>>ovciflowO diould return EOF to indicate an error oriterwise it 
should return someriung dse. 

issb>>pbadc£ail(c) 

Is called when ebadcO equals gptrO and an attempt has been made to putback 
c If riiis situation can be dealt with (e.g., repositioning an external file), 
pbadcfailO dioukl return c otherwise it diould return EOF. 

posatsb>>sed(Q£f(o^ dir mode) 

Repositions riie get and/or put pointers (Le., rite abstract get and put pointers, 
not pptrO and gptiO). The meanings of off and dir are discussed in 
sbuf.piM3C+*). mode ^ledfies whether rite put pointer (ios:: out lat set) or 
the get poiitter (ios: :ln bit set) is to be ntodified. Borit bits may be set in 
which case borit pomters dtould be afiecled. A derived horn stream- 
buf is rtot requiiWl to support reposirioniz^. seekoffO should return EOF if 
the dass does not scqtport rqtositkming. If rite class does support reposition- 
ii^ seekoffO should return rite rtew positicm or EOF on error. 

posssb>>sed:pos(pos, mode) 

Repositions the streaaibuf get and/or put poirtter to pos. mode specifies 
vdtich poittters are affected as for sedcoffO. Returns pos (rite arguntent) or 
EOF if the dass does rtot suppmt rqiosiriotting or an error occurs. 

sb«sb>>sefo«f(ptr, len) 

Offers rite array at ptr wirit len bytes to be used as a reserve area. The itortnal 
interpretation is ritat if ptr or len are zero then ritis is a request to ntake the sb 
uttbuffered. The derived dass may use ritis area or not as it dtooses. If ntay 
accept or ^nore rite request for unbuffered state as it chooses. setbufO should 
return sb if it hmtcMS the request Oriterwise it dtould return 0. 

issb>>syncO 

Is called to give the derived dass a chance to look at the state of the areas, and 
synchronize them with any external repre s entation. Normally syncO should 
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constune any characters ttiat have been stored into ttie put area, and if possi¬ 
ble give back to the source aiqr characters in the get area ttiat have not been 
fetdied. When ^nc() returns there should not be any unconsumed characters, 
and the get area should be en^>ty. S)mcO should return EOF if some kind of 
failure occurs. 

issb->nnderflowO 

Is called to supply diaracters for fetdiing, Le., to create a condition in which 
the get area is not empty. If it is called when there are diaracters in the get 
area it should return ttie first character. If the get area is empty, it should 
create a nonempty get area and return the next character (whidi it should also 
leave in the get area). If there are no more diaracters available, tutderflowO 
should return EOF and leave an en^^ get area. 

The default definitions of ttie virtual functions: 

i=sb->streambufsdoallocateO 

Attempts to aUocate a reserve area using operator new. 

issb->streambufiu>vetflow<c) 

Is compatil:^ with die dd stream padcage, but that behavior is not considered 
part of ttie ^ledfication of the iostream package. Therefore, 
streambufooverflot^) should be treated as if it had undefined behavior. That 
is, derived classes should always define it 

issb->streambnfopbackfail(c) 

Returns EOF. 

posssb->streambu£sseelq>os(pos, mode) 

Returns sb->seeko£f(stieamotf(pos)4os=bcg,mode). Thus to define seddng in 
a derived class, it is fiequen^ only necessary to define seekoffO and use the 
inherited streambufsseekposO. 

pos=sb->streambnfi:seekoff(o£^ dir, mode) 

Returns EOF. 

sb=sb->streambufosetbuf(ptr, len) 

Will honor the request when thoe is no reserve area. 

issb->streambnfss 3 mc() 

Returns 0 if ttie get area is eirqrty and there are no unconsumed characters. 
Ottierwise it returns EOF. 

issb->5treambufonndetflow() 

Is compatible with the (rid stream package, but that behavior is not considered 
part of ttie specification of the iostream package. Therefore, 
streambufsnnderflowO should be treated as if it had undefined behavior. That 
is, it ^uld always be defined in derived classes. 

CAVEATS 

The constructors are public for compatibUiQr with ttie crid stream package. They ought to be 
protected. 

The interface for unbuffered actions is awkward. It's hard to %vrite undezflowO and overflowf) 
virtuals that behave properly for unbufiered stceambufOs widiout special easily. Also 
there is no way for the viituals to react sensilriy to multi-character gets or puts. 

Althou^ ttie public interface to stceanbufs deals in characters and bytes, the interface to 
derived classes deals in chars. Sines a decision had to be made on the types of the real data 
pointers, it seemed easier to reflect that choice in the types of the protected members than to 
duplicate all ttie members with both plain and unsign^ char versions. But perhaps all these 
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uses of char* ou^t to have been witf\ a typedef. 

The implementation contains a variant of settufC) that accepts a third argument. It is present 
only for compatibility witft the old stream padcage. 

SEE ALSO 

sbuf.pubOC-M'), streambuf(3C<M'), iostrBain(3C<M-) 
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NAME 

streambuf - public interfoce of diaracter burring Hacc 
SYNOPSIS 

#inclade <iostreainJi> 


lypedeT long streamofT, streampos; 

ios { 
public 


} ; 


VUIBIU 








“““ open_iiiode { in, out, ate, app, trunc, nocreate, noreplace 

// and lots of other stuff ... See ios(3C+^) 


class streambuf { 
public : 

int 

int 

int 

streambuf^ 

streampos 

streampos 

int 

int 

int 

int 

int 

int 

void 

virtual int 

}; 


ui_availO; 

ont^wahingO; 

sbumpeO; 

setbofCdiar* ptr, int ten); 
seekposfstrcampos, int sios::in|ios::oot); 
seekofKstreamofr, seek dir, int =ios::iniios::ont); 
SgetcO; 

sgetn(char* ptr, int n); 
snezteO; 
sputbackefehar); 
sputcOnt c); 

spntnfconst char* s, int n); 
stosscQ; 

5ync0; 


DESaUFTlON 

The streambuf class supports bufi^ into which characters can be inserted (put) or from 
wfa«|h charters can be fetched (gotten). Abstractly, such a buffer is a sequence of characters 
top^ with one or two pointers (a get and/or a put pointer) that define the location at 
^ch diaracters are to be inserted or fetched. The pointers should be tfiouAt of as pointine 
between characters laflier than at them. This makes it easier to understand the boundary con- 
dilrons (a pomto before the first character or after the last). Some of the effects of getting and 
^ttmg are defined by this class but most of the detaib are left to specialized clas^ dAved 
from streambuf. (See fUebt^SC-M-), ssbt^SC-M-), aiei stdwbuf(3C++).) 

Oass^ derived from streambuf vary in their treatments of the get and put pointers. The 
simplest are unidirectional buffers which permit only gets or only puts. Such d^es serve as 
pure sources ({woducers) or sinks (consumers) of diaracters. ^euelike buffers (ee see 

a put and a get pointer which move independOTfiy of 
Stored are held (Le., queued) until Aq. are later 
fetched. FUelike buffers (eg., f ilebuf, see faAuf(3C**)) permit boA gets and puts but have 
only a single pointer. (An alternative description is that the get and put pointers are tied 
together so that when one moves so does the other.) 


Most streambuf men^r functions are organized into two phases. As far as possible, opera¬ 
tions are performed inline by storing mto or fetching from arrays (Ae get area and the put area 
which together form the reserve area, or Iw jfer). From time to time, virtual functions are called 
to deal with collections of characters in the get and put areas. That is, Ae virtual functions are 
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called to fetch more characters from ttie ultimate producer or to flush a collection of charac¬ 
ters to the ultimate consumer. Generally ttie user of a streambuf does not have to know 
anything about these detaib, but some of the public members pass back information about the 
state of the areas. Further detail about fltese areas is provided in sbuf.prot(3C+*), v^diich 
describes the protected interface. 

The public member functions of the streaaibuf class are described below. In tite following 
descriptions assume: 

— i, n, and len are ints. 

— c is an int. It always holds a "character” value or EOF. A 'charactef” value is always 
poative even when char is normally sign extended. 

— sb and sbl are streaiitouf*s. 

— ptrisa char*. 

— off is a streanoff. 

— pos is a streanpos. 

— dir is a seek_dir. 

— mode is an int re p r e s e nting an openjnode. 

Public member fuitctions: 

issb->in_availO 

^tums the number of diaracters that are immediately available in the get area for 
fetching, i dtaracters may be fetched witft a guarantee that no errors will be reported. 

iasb>>ont_waitiiigO 

Returns the number of duuacters in the put area that have not been consumed (by the 
ultimate consumer). 

cssb->sbumpc() 

Moves the get pointer forward <me character and returns the diaracter it moved past. 
Returns EOF if the get pointer is currently at tfie end of the sequence. 

posssb->seeko£f(o£f, dir, mode) 

Repositions the get and/or put pointers, mode specifies whether toe put pointer 
(ios: tout bit set) or the get pointer (ios: :in bit set) is to be modified. Both bits 
may be set in which case both pointers should be affected, off is interpreted as a byte 
ofeset. (Notice tiiat it is a signed quantity.) The meanings of possible values of dir are 

ios::beg 

The beginning of the stream. 

ios::cuc 

The current position. 

ios:tend 

The end of the stream (end of file.) 

Not all cl a s s es derived from streambuf suf^>ort repositioning. seekoffO will return EOF if 
the dass does not support repositioning. If the class does support reporitioning, seekoffO will 
return the new position or EOF on error. 

posssb->seekpos(pos, mode) 

Repositioirs the streanibuf get and/or put pointer to pos. mode ^>ecifies which 
pointers are affected as for seekoffO. Returns pos (the argument) or EOF if the 
does trot support repositioning or an error occurs. In general a stcean^s should be 
treated as a "magic cookie" and no arithmetic should be performed on it. Two particu¬ 
lar values have special meaning: 

streampos(0) 

The begiiming of toe file. 
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streampos(EOF) 

Used as an error indication. 

cssb>>sgetc() 

Returns the duuacter after the get pointer. Contrary to what most people expect from 
the name IT DOES NOT MOVE THE GET POINTER. Returns EOF if there is no char¬ 
acter available. 

sblssb->setbttf(ptr, len, i) 

Offers the len bytes starting at ptr as the reserve area. If ptr is null or len is zero or 
less, then an unbuffered state is requested. Whether the o^ered area is used, or a 
request for unbuffered state is lumored depends on details of foe derived Ha«» set- 
bnfO tu>nnally returns sb, but if it does not accept the offer or honor foe request, it 
returns 0. 

issb->sgetn(ptr, n) 

Fetches foe n characters foUowir^ foe get pointer and copies them to the area starting 
at ptr. When there are fewer than n characters left before foe end of the sequence 
sgetnO fetches whatever characters remain. sgetnO repositions the get pointer follow¬ 
ing the fetched characters and returns foe number of dUracters fetched. 

cssb->snextcO 

Moves the get pointer forward otte character and returns the character following the 
new positiotL It returns EOF if the pointer is currently at foe end of the secjuence or is 
at the etKi of the sequetrce after moving forward. 

issb->spatbackc(c) 

Moves foe get pointer back one character, c must be the current content of the 
secpience just before the get pointer. The underlying mechanism may simply back up 
foe get pointer or may rearrange its internal data structures so the c is saved. Thus the 
eff^ of spntbadccO is undefirted if c is not the character before foe get pointer, sput- 
backcO returns EOF when it fails. The conditions under which it can fail depend on 
foe details of the derived dass. 

i3sb->sputc(d 

Stores c after the put pcnnter, artd moves foe put pointer past the stored diaracter; usu¬ 
ally this extends the secpience. It returns EOF when an error occurs. The coiKlitions 
foat can cause errors depend on the derived 

issb->spntn(ptr, tO 

Stores the n characters starting at ptr after foe put pointer arxl moves the put pointer 
past them. sputnO returns i, foe number of dtaracters stored successfully. Normally i 
is n, but it rruy be less when error s occur. 

sb->stossc0 

Moves the get pointer forward one character. If the pointer started at foe end of the 
secjuence this function has no effect 

issb->S3mc0 

Establishes consistency between the internal data structures and the external source or 
sink. The detaik of this function deperxl on foe derived dass. Usually fois “flushes" 
any characters that have been stored but not yet consumed, and “gives back" any char¬ 
acters foat nuty have been produced but not yet fetched. syncO returns EOF to indi¬ 
cate errors. 


CAVEATS 

setbuf does not really belong in the public interface. It is there for compatibility with the 
stream package. 
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Requiring tfte program to provide the previously fetched character to sputback is probably a 
bot^ 

SEE ALSO 

iostreamOC-M-), sbuf.proK3C++) 
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NAME 

strstreambuf - streambuf specialized to arrays 
SYNOPSIS 

Bindode <iostreamJi> 

Bindude <strstreamJi> 

class strsdrcaoibitf : public streaaibiif { 
pubik: 

strstreambafO ; 

sti'sb eafflbaf(cfaar*, int, cbar*); 
s trsIre am ImlOt); 

strstrcanbafCiiBsigBCd cfaar*^ intt oosigiied char*); 
strstreambaKToid* (•aXloog), ▼oid(*fKvoid*)); 

void freezeGat asl) ; 

char* strQ; 

streambnf* setbiif(cbar*, iat) 

); 

DESOUPnON 

A strstreambuf is a streaadbuf that uses an array of lytes (a strii^ to hold Oie sequence 
of characters. Given the convention tfiat a char* should be interpreted as pointiiig just 
before the char it really points at, flte mapping between the abstract get/put pointers (see 
d>uf.pub(3C-t-^)) and char* pointers is direct Movit^ the pointers corre^wnds exactly to 
incrementmg and decrennenting die char* values. 

To aocommodate die need for aiinttary ler^th struts strstreambuf supports a dynamic 
mode. When a strstreambuf is in dynamic mode, qmce for die diaracter sequence is allo¬ 
cated as needed. When die sequence is extended too far, it will be copied to a new array. 

In the following descriptions assume: 

— ssb is a strstreambuf*. 

— nisan int. 

— ptr and pstart are char*s or unsigned char*s. 

— a is a void* {*) (long). 

— f is a void* (*) (void*). 

Constructors:: 

strstreambufO 

Constructs an empty^ strstreambuf in dynamic mode. This means that 
^ce will be automatically allocated to accomodate die characters that are put 
into die strstreambuf (using operators new and delete). Because this 
may require copying the original diaracters, it is recommended that when 
many diaracters will be inserted, the program should use setbufO (described 
bebw) to inform the strstreambuf. 

strstreambuf(a, f) 

Constructs an empty strstreambuf in dynamic mode, a is used as the allo¬ 
cator function in dynamic mode. The argument passed to a will be a long 
denotirg die number of bytes to be allocated. If a is null, operator new will 
be used, f is used to free (or delete) areas returned by a. The argument to f 
will be a pointer to the array allocated by a. If f is null, operator delete is 
used. 

strstreambufin) 

Constructs an empty strstreambuf in dynamic mode. The initial allocation 
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of space %vill be at least n bytes, 
strstreambuffptr, n, pstait) 

Constructs a strstreambuf to use the bytes starting at ptr. The 
strstreambuf will be in static nnode; it will not grow dynamically. If n is 
positive, then the n bytes starting at ptr are used as the strstreambuf. If n 
is zero, ptr is to point to the beginning of a null terminated string 

and the bytes of that string (not including die terminating null diaracter) will 
constitute the strstreambuf. If n is negative, the strstreasibuf is 
assumed to continue indefinitely. The get pointer is initialized to ptr. The put 
pointer is mitiaiiwid to pstart If pstart is null, then stores will be treated as 
enors. If pstart is non>nuU, then die initial sequence for fetching (the get area) 
of die bytes between ptr and pstart If pstart is null, then the initial 
get area consists of die entire array. 

Member functions: 

ssb'>£reeze(n) 

Inhibits (when n is nonzero) or permits (when n is zero) automatic ddedon of 
the current array. Deletion normally occurs when more space is needed or 
when ssb is being destroyed. Only ^ce obtained via dynamic allocation is 
ever foeed. It is an error (and die effect is undefined) to store diaracters into a 
strstreambuf diat was in dynamic allocation mode and is now frozen. It is 
possible, ho%vever, to diaw (unfreeze) sudi a strstreambuf and resume stor¬ 
ing diaracters. 

ptr3ssb->str0 

Returns a pointer to the first char of the current array and freezes ssb. If ssb 
was constnicted with an eiqilidt array, ptr will point to that array. If ssb is in 
dynamic allocation mode, but nodiing has yet bm stored, ptr may be null. 

ssb->sefouf(0,n) 

ssb remembers n and the next time it does a dynamic mode allocation, it 
makes sure that at least n bytes are allocated. 

SEE ALSO 

sbuf.pub(3C++), strstream(3C++) 
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NAME 

stdiobuf - iostream specialized to stdio FILE 
SYNOPSIS 

#include <ia5treamJi> 

#include <stdiostream.b> 

#include <stdioJi> 

class stdiobuf : public streambuf { 

stdiobufcnLE* 0; 

FILE* stdiofileO; 

}; 

DESCRIPnON 

Operations on a stdiobuf are reflected on Are associated FILE. A stdiobuf is constructed 
in unbuffered mode, which causes all operations to be reflected immediately in the FILE. 
seekgOs and seekpOs are translated into fseekOs. setbuff) has its usual meaning; if it supplies 
a reserve area, buffering will be turned back on. 

CAVEATS 

stdiobuf is intended to be used wdren mixing C and C++ code. New C++ code should 
prefer to use filebufs, which have better performance. 

SEE ALSO 

filebuf(3C++), istream(3C++), ostream(3C++), sbuf.pub(3C++) 
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NAME 

strstream - iostream qiedalized to arni)rs 
SYNOPSIS 

#indade <strstre ai aJi> 

class ios { 
public: 

CBum opcnjBode { ia, out, ate, app, trunc, nocreate, norcpiace } ; 

// and tots of ofSter sbig, see ios(3C-ht) ^ 

} ; 

dass istrstrcam : public i stre ai u { 
pubGc 

istrstr au nCchar*) ; 
istrstrcaai(char*, iut) ; 
strstreanbuf* rdbnfO ; 

} ; 


dass ostrstrea m : public ostr e am { 
public 

ostrstreanO; 

ostrstreaai(char*, iut, intsios::out) ; 
int pcountO ; 

strstreambuf* rdbufO ; 
char* strO; 

}; 

dass strstream : public strstreambase, public iostream { 
public 

strstreamO; 

s tr s tre a m(char*, iat, iat amde); 
strstreambuf* rdbafO ; 
char* strO; 

}; 

DESCRIPTION 

strstream ^Tedalizes iostream ’’incore*' operations, that is, storing and fdddng from 
arrays of byt^ The streambuf associated wito a strstream is a strstreaadbuf (see 
ssb«K3C++». 

In the foOowing descriptions asmune: 

— ss is a strstream. 

— iss is an Istrstream. 

— OSS is an ostrstream. 

— cp is a char*. 

— mode is an int representing an open^otode. 

— i and len are ints. 

— ssb is a strstreeuidduf*. 

Constructors 

istrstream(cp) 

Characters will be fetched from the (null-terminated) string cp. The terminat¬ 
ing null character %vill not be part of the sequeiKe. Seeks (istreamrseekgO) are 
allowed within that space. 
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ististreain(q>, len) 

Characters will be fetched horn the array beginning at cp and extending for 
len bytes. Seeks (istreamsseekgO) are allowed anywhere within that array. 

ostrstreamO 

Space will be dynamically allocated to hold stored diaracters. 
ostxstreamfcp^^node) 

Characters will be stored into the array starting at cp and continuing for n 
bytes. If los: :ate or ios: :app is set in mode, q> is assumed to be a null- 
terminated string and storing will begin at the null character. Otherwise stor¬ 
ing will begin at cp. Seeks are allowed anywhere in the array. 

strstxeamO 

Space will be dynamically allocated to hold stored characters. 
strstream(cp,n,mode) 

Characters will be stored into the array starting at cp and continuing for n 
bytes. If ios:: ate or ios:: app is set in mode, cp is assumed to be a null- 
terminated string aiKl storing mil begin at the null character. Otherwise stor¬ 
ing will begin at cp. Seeks are allowed anywhere in the array. 

istrstreasn members 

ssb s issjdbufO 

Returns the strstreanbuf associated with iss. 

ostrstream members 

ssb s os&jdbufO 

Returns the strstreanbuf associated with oss. 
cpsos&stiO 

Returns a pointer to the array being used and "freezes" tiie array. Once str has 
been called dre effect of storing more characters into oss is undefined. If oss 
was constructed mth an e]q>licit array, cp is |ust a pointer to the array. Other¬ 
wise, cp points to a dynamically allocated area. Until str is called, deleting the 
dynamically allocated area is the resportsibility of oss. After str returns, the 
array becomes the responsibility of tire user program. 

isoss.pcounK) 

Returns the number of bytes that have been stored into the buffer. This is 
mainly of use when binary data has been stored and oss.stTO does not point to 
a null terminated string. 

strstreant members 

ssb s ss.rdbnf() 

Returns the strstreanbuf associated with ss. 
q>sss.stt() 

Returns a pointer to the array being used aird "freezes* the array. Once str has 
been called die edect of storir^ n»re characters into ss is urvdefined. If ss was 
constructed widr an explicit array, cp is |ust a pointer to the array. Otherwise, 
cp points to a dynamically allocated area. Until str is called, deleting the 
dynamically allocated area is die responsibility of ss. After str returns, the 
array becomes the responsibility of the user program. 

SEE ALSO 

strstreambuf(3C++), iostream(3C++) 
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etKapsuIation 2:17-19 
endl manipulattH’ 3:6,17 
eofbit constant 3:5 
emn- state, stream 3:5 
errors 

in iostieams 3:5 
pv^gation of 3:5 
examples 
action 3:24 
fcOiase 3:30 
fdbttf 3:24 
fld 3:18-19 
ifctstream 3:30 
indent 3: 31 
Indent_init 3: 31-32 
in_kO 3:19 
iofctstream 3: 30 
Longref 3:19 
ofctstream 3:30 
Pair 3:3-4,7,15-16 
redent 3:31 
lepeaiO 3: 20 
Repeatpair 3:20 
tab 3:18 
Vec 3:4 
Vecfl 3:4^ 8 
xdent 3:31 
extraction operators 
dun 3; 7-8 
char* 3: 9 
float 3:8 
int 3: 7,12 
long 3:19 
user defined 3:7,9 
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frilbit constant 3:5 
fctbttf dass 3:24-30 
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fill state variable 3:16 
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filters 2; 15-16 
fixed 3: 14 

fiagsO function 3: 8,19 
flags state variable 3:15 
flush manipulator 3; 6,17 
flushing, in iostreams 3: 5-6 
frame pointers 2: 41 
FramelayoutO structure 2:49 
fstreamO constructor 3:11-12 
fstream iostream 3:11-12 
fudging parent stack 2: 45-47 
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get() function 3: 7, 9-10,13 
goodO function 3: 5 
goodbit constant 3: 5 
gptrf) function 3: 27,29 
gptr pointer 3: 29 
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hex maniptilator 3:14,17 
histograms 2:19-20 
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lAPP macro 3:19 

ifstream class 3:10 

ifstreamO constructor 3:10,13,35 

ignored function 3:19 

in 3:11-12, 29-30 

in_avail() 3: 22 

incore formatting 3:12-13, 34 

iniK) function 3: 30 

initialization, stream 3: 32 

input 3: 6-10 

insertion operator («) 3: 2-3 
insertion operators 
char 3: 3,6,18,31 
char, in old stream library 3: 36 
char* 3: 3—4, 6, 20 
float 3:4 
int 3: 4 

numeric 3: 2-3 
user defined 3: 3-4 
void* 3: 3 
interference 2: 30 
interrupt alerters 2: 29 
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interrupts 2: 31-33 
lOMANIPdeclare macro 3:19-20 
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io_state 3:5 
iosbeam class 3: 2 
deriving from 3: 30 
problems with 3:33 
iostream library 3:1-37 
initialization 3:32 
Iostream_iiiit 3: 32 
iostream^ 

base conversion of integers 3:16-17 
buffers 3: 22-23 
format control 3:14-18 
manipulators 3:18-20 
predefmed 3:13 
sequence abstraction 3:20-23 
state variables 3:17 
underflow 3: 29 
istream* 3:13 
istieam class 3: 2 
deriving from 3:30 
istreamO constructor 3: 23 
obsolete form 3: 34-35 
istrstreamO constructor 3:12,35 
iwordO function 3: 31 
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left constant 3:14,16 
libraries 

iostream 3:1-37 
task 2:1-50 
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rtuin task 2:11 
marupulators 3:6 
iostream 3:18-20 
rtressages 2:6-7,17-18 
definition of 2:6 
mixed mode arithrrtetic 1: 5 
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nocreate constant 3:11 
noreplace constant 3:11 
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OAPP macro 3:31 

object class 2: 29 

oct manipulator 3:14,17-19 

ofstream class 3:10 

ofetreamO constructor 3:10-11,35 

OMANIP macro 3; 19-20 

openO function 3:10-11 

open_mode 3:11,24 

operator !, in stream 3: 5 

operator void*, in stream 3:5 

operators 

for type complex 1:1-2,4 
input 1: 3-4 
output 1:3-4 
ostream class 3:2 
deriving from 3:30 
ostieamO constructor 3: 23 
obsolete form 3:34-35 
ostream_witfaassign class 3:36 
ostrstreamO constructor 3:12,34 
out 3:11-12,27,30 
output 3:2-6 

ovetflowO function 3: 24, 27,29 
overheads 2: 22-23 



pbaseO function 3: 27,29 
phase pointer 3: 28 
peekO fmtction 3:8-9,16,19 
performance 2:22-23 
polar coordiiudes 1:4 
in type complex 1:2 
porting guide 2: 38-50 
pptK) function 3:27,29 
pptr pointer 3:28 
precision state variable 3:17 
preemptO function 2:13 
printO function 2:19,22 
puH) function 3:6,10,13,18 
putbackO function 3: 29 
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qhead class 2: 2 
qtail class 2: 2 

queues 2: 5-10,12,15-17, 38 
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random numbers 2:1SK20 
zdbulO function 3: 21 
idstaleO functim 3:7-8 
xeadO function 3:10 
real-time extensions 2:29 
remember diain 2:28 
resetiosfiags manipulator 3:14,17 
lesulfisO function 2:5,11 
fight dmstant 3:14,16 
run drain 2:27 
run time errors 2:24 
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sbttiiq>e0 function 3:21 
sdieddass 2:3 
scheduler 2:27,29,33,38 
scheduling 2:21 
sdentihc constant 3:14 
seekgO function 3:12 
semai^rores 2:30-31 
Server dass 2:18 
server tasks 2:6 
selhO function 3:25 
sctbnfO function 3:23-26 
obsdetefoim 3:34 
setff) function 3:14,16—18 
set^ function 3:25,27,29 
setiosflags manipulator 3:14 
se^ function 3:25,28-29 
setrvO function 3:19 
setw man^xilatCH’ 3:9,16 
sgetcO fuiidion 3: 21-22 
^etnO function 3:22 
SHARED tasks 2:41,43 
shoivbase, 3:16 
showbase constant 3:14,18-19 
showpoint constant 3:14 
showpos constant 3:14 
simulated time 2:2 
simulations 2:27 
skqrws cmstant 3:8,14-15 
sncxtcO function 3:21 
source file organization 2:50 
Spaces dass 2:4 
sputcO fuirction 3:21 
sputnO function 3:22 
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muting witii iostream 3:13 
piobleins with 3:32 
stdiobof class 3:35 
stdiostream class 3:35 
sbO function 3:13 
stream library 
converting horn 3:33 
problems witii 3:32 
streambuf dass 3: 20-21,23 
deriving from 3:24-30,33 
streambufO constructor, obsolete form 3:34 
streampos 3:12 
streams 

extending 3:30 
predefined 3:13 
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stistreamO constructor 3:12 
strstreambnf class 3:23 
strstreambufO constructor 3: 34 
swjqK) function 2:42,44 
syncO functicm 3: 23-24,29 
sync_,withj5tdioO function 3:13,36 
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onderflowO fimction 3: 24, 28 
uppercase omstant 3:14 
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waiting 2:11-15 
waidisti) function 2:12 
waitvcc function 2:13 
white^iace, skippir^ 3:6 
widliiO function 3:9,1&>16,18 
width state variable 3:15 
wxiteO function 3:6,16 
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xallocO function 3:31 
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target machines 2: 38 
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task library 2:1-53 
task stack allocation 2: 21 
task state 2: 38 

task switching fundamentals 2:38-41 
task switching irr^lementation 2:41-49 
task_eixoiO function 2:22 
tasks 

definition of 2:2 
IDLE state 2:4 
RUNNING state 2:4 
HERMINATED state 2:4 
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